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. Hitachi will not be held responsible for any damage to the user that may result from accidents 
or any other reasons during operation of the user’s unit according to this document. 


. Circuitry and other examples described herein are meant merely to indicate the characteristics 
and performance of Hitachi’s semiconductor products. Hitachi assumes no responsibility for 
any intellectual property claims or other problems that may result from applications based on 
the examples described herein. 


. No license is granted by implication or otherwise under any patents or other rights of any third 
party or Hitachi, Ltd. 


. MEDICAL APPLICATIONS: Hitachi’s products are not authorized for use in MEDICAL 
APPLICATIONS without the written consent of the appropriate officer of Hitachi’s sales 
company. Such use includes, but is not limited to, use in life support systems. Buyers of 
Hitachi’s products are requested to notify the relevant Hitachi sales offices when planning to 
use the products in MEDICAL APPLICATIONS. 


Preface 


This manual explains how to use the SuperH RISC engine C/C++ compiler (hereafter SH C/C++ 
compiler or simply the compiler). Please read this manual before using the compiler to fully 
understand the system. The compiler translates source programs written in C/C++ language into 
relocatable object programs or assembly source programs for SuperH RISC engine family 
microcomputers (SH-1, SH-2, SH-2E, SH-3, SH-3E, and SH-4). 


Features of this compiler system are as follows: 


1. generates an object program that can be written to ROM to be installed in a user system. 


supports an optimization option that improves the execution speed of object programs or 
minimizes program size. 


supports program description languages C and C++. 


4. for programs described in C, provides the debugging-information output option to analyze C 


sources using the C source level debugger, and for programs described in C++, provides the 
debugging-information and browser-information options to analyze C++ sources using the 
C++ source level debugger and browser. 

is able to select and output either an assembly source program or a relocatable object program. 
supports the inter-module optimization information output option that outputs necessary 
additional information for the inter-module optimizer. 


This manual consists of eight parts and appendixes. The information contained in each part is 
summarized below. 


lk. 


OVERVIEW AND OPERATIONS 

The overview section covers compiler functions and developing procedures. 

The operation section covers how to invoke the compiler, how to specify optional functions, 
and how to interpret list files created by the compiler. 

C/C++ PROGRAMMING 


This part explains the limitations of the compiler and the special factors in object program 
execution which should be considered when creating a program. 


. SYSTEM INSTALLATION 


This part explains the object program being written in ROM and memory allocation when 
installing an object program generated by the compiler on a system. In addition, 
specifications of low-level interface routine must be made by the user when using standard I/O 
library and memory management library. 


. ERROR MESSAGES 


This part explains the error messages corresponding to compilation errors and the standard 
library error messages corresponding to run time errors. 
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5. INTER-MODULE OPTIMIZER 
This part explains the functionality, usage, and the object format conversion function of the 
inter-module optimizer that optimizes the output object program of the compiler for linked 
modules. 

6. ERROR MESSAGES DURING INTER-MODULE OPTIMIZATION 
This part explains the error messages of errors that may occur during execution of the inter- 
module optimizer. 

7. STANDARD LIBRARY 
This part explains the specifications of the standard library functions that can be called from 
C/C++ programs. Standard library functions not supported by the SH C/C++ compiler are 
listed in APPENDIX A.2 (9), Unsupported Library Functions. Be sure to check it. 

8. DSP LIBRARY 


This part explains the specifications of the library for digital signal processing (DSP) such as 
fast Fourier transforms and digital filtering. 


This manual is intended for UNIX*', Microsoft® Windows” 95 operating system*”, and 
Microsoft® WindowsNT® operating system*’ that runs on an IBM PC*°, and other compatible 
computers. In this document, the compiler functioning on a UNIX system is referred to as the 
UNIX version. Compiler operating in IBM PC** and other compatible computers are referred to 
as the PC version. 


Notes on Symbols: The following symbols are used in this manual. 


Symbols Used in This Manual 


Symbol 


<> 


Notes: 1. 


=. 


Explanation 

Indicates an item to be specified. 

Indicates an item that can be omitted. 

Indicates that the preceding item can be repeated. 
Indicates one or more blanks. 

Indicates the carriage return key (return key). 
Indicates that one of the items must be selected. 


Indicates that the control key should be held down while pressing the key 
that follows. 


UNIX is a registered trademark in the United States and other countries, licensed 
exclusively through X/Open Company Limited. 


Microsoft®, Windows”, and WindowsNT™ are registered trademarks of Microsoft 
Corporation in the United States and/or other countries. 


IBM PC is a registered trademark of International Business Machines Corporation. 
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Notes on the Compiler Version Upgrade 


When you develop a program with the upgraded compiler, take care of the following and carefully 
test your program since the operation of the program may change depending on the compiler 
version. 


1. Programs Depending on Execution Time and Timing 
C/C++ language specifications do not specify the program execution time. Therefore, a 
version difference in the compiler may cause operation changes due to timing lag with the 
program execution time and peripherals such as the I/O, or processing time differences in 
asynchronous processing, such as in interrupts. 


2. Programs Including an Expression with Two or More Side Effects 


Operations may change depending on the compiler version when two or more side effects are 
included in one expression. 


Example 
a[i++]=b[i++] ; /* i increment order is undefined. */ 
£(i++, i++); /* Parameter value changes according to increment order. */ 


/* This results in f(3, 4) or f(4, 3) when the value of i is 3. */ 


3. Programs with Overflow Results or an Illegal Operation 


The value of the result is not guaranteed when an overflow occurs and an illegal operation is 
performed. Operation of the program may change depending on the compiler version. 


Example 

int a, b; 

x= (a*b) /10; /* This may cause an overflow depending on the value range of 
a and b. */ 
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4. No Initialization of Variables and Type Inequality 


When a variable is not initialized or the parameter and return value types do not match 
between the calling and called functions, an incorrect value is accessed. Operation of the 
program may change depending on the compiler version. 


Example 
file 1: 
int f(double d) 


{ 


} 
file 2: 


£ (2) 3 


The parameter of the function-calling file is the int type, but the parameter of the function- 
defining file is the double type. Therefore, a value cannot be correctly referenced. 


The information provided here does not include all cases that may occur. Please use this compiler 
prudently, and sufficiently test your programs keeping the differences between the compiler 
versions in mind. 
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Section | Overview and Operations 


1.1 Overview 


The SuperH RISC engine C/C++ compiler translates source programs written in C or C++ 
language into a relocatable object program or an assembly source program for SuperH RISC 
engine family microcomputers. This compiler supports the SH-1, SH-2, SH-2E, SH-3, SH-3E, 
and SH-4. 


Raocatahle 
SuperH AlSO engine object program 
ChCH+ compiler for SuperH 
RISO engine farrily 
Tic mom puter 


CCH SOU me 

program 
Assembly sou me 
program 
for SuperH 
RISC engine farrily 
ric moomputer 


Figure 1.1 Compiler Function 


This manual explains the standard library (a collection of C language level functions used as the 
standards and run-time routine group written in C/C++ programs), embedded C++ library 
(embedded C++ class library), DSP library (digital signal processing library function group), and 
inter-module optimizer. Note that the embedded C++ library is not supported by the compiler 
version 5.0. 
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1.2 Developing Procedures 


Figure 1.2 shows the relationship between the compiler package and other software for program 
development. The compiler package includes the software enclosed by the dotted line. 


: SuperH RISC engine: 


MM chewet 
1. deeerkly ecurce pcre ere cutput depending on option apeciobon. 
- Standard library Punctons, arbedded Ce+ Eran funcbone [ict susible in Per S.0, CSP livery 
Furcbona, and receny recrone nee bo ueethe bbreriee are defied. 
Debugging infomation can sleobesdded depending on option epechoalon 
A function group, coneiebng of 0 Bbrary Purctone and rurebercubes, poured se etanderd in the OAC++ program 
. Afar compl ebng opiiabon, theinierncduecpimine suborabedky schates thelinka ge editor. 


Figure 1.2 Relationship between the Compiler and Other Software 
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1.3 Compiler Execution 


This section explains how to invoke the compiler, specify compiler options, and interpret compiler 
listings. 


1.3.1 How to Invoke the Compiler 
The format for the command line used to invoke the compiler is as follows. 


shc [A<option>...] [A<file name>[A<option>... 


shcpp [A<option>...] [A<file name>[A<option>... 


The shc command performs C compilation* or C++ compilation* to C or C++ program 
respectively, according to the lang option or the extension of the program file name. The shcpp 
command performs C++ compilation regardless of whether the program is written in C or C++. 


Note: In this manual, C compilation means compilation according to the C language syntax, and 
C++ compilation means compilation according to the C++ language syntax. 


The basic operations of the compiler are described below. 
(1) Compiling Programs 

shcAtest.c (RET) 
The C source program test.c is compiled. 


shcAtest.cpp (RET) 


shcppAtest.cpp (RET) 


The C++ source program test.cpp is compiled. 


(2) Displaying Command Line Format and Compiler Options 


she (RET) 
shcpp (RET) 


The command line format and the list of the compiler options are displayed on the screen. 
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(3) Compiler Options 


Insert hyphen (—) before options (such as debug, list file, and show). Slash (/) can also be 
inserted in place of hyphen (—) for PC version. When multiple options are specified, separate 
them with a space (A). The following shows the options for UNIX version and PC version. Also 
when multiple suboptions are specified, separate them with a comma (,). 


shcA-debugA-listfileA-show=noobject,expansionAtest.c (RET) 

In PC version, when multiple suboptions are specified, they can be enclosed in parentheses (( )). 
shcA/debugA/listfileA/show= (noobject, expansion) Atest.c (RET) 

(4) Compiling Multiple C/C++ Programs 


Multiple C/C++ programs can be compiled by a single command. Examples of C source program 
compilation are shown below. 


Example 1: Specifying multiple programs 


shcAtestl1.cAtest2.c (RET) 


Example 2: Specifying options for all C source programs 
shcA-listfileAtest1.cAtest2.c (RET) 

The listfile option is valid for both test1.c and test2.c. 

Example 3: Specifying options for particular C source programs 


shcAtest1.cAtest2.cA-listfile (RET) 


The listfile option is valid for only test2.c. Options specified for particular source programs have 
priority over those specified for all source programs. 


Rev. 1.0, 09/98, page 4 of476 


HITACHI 


1.3.2 Naming Files 


A standard file extension is automatically added to the name of a compiled file when omitted. The 
standard file extensions used by the compiler and related software are shown in table 1.1. For 
details on naming files, refer to the user's manual of the host computer because naming rules vary 
according to each host computer. 


Table 1.1 Standard File Extensions Used by the Compiler and Related Software 


No. File Extension Description 

1 Cc Source program file written in C 

2 cpp, cc, cp, CC Source program file written in C++ 

3 h Include file 

4 lis, Ist, Ipp Listing file*'*? 

5 p, pp File after the expansion by the preprocessor ***° 
6 obj Relocatable object program file*? 

7 src Assembly source program file*? 

8 dtb Debugging information file** 

9 iop Inter-module optimizing information file** 

10 dwi Information file for DWARF format conversion** 
11 lib Library file 

12 abs Absolute load module file 

13 rel Relocatable load module file 

14 map Linkage map listing file 


Note: 1. The extension is lis for UNIX version at C or C++ compilation, Ist for PC version at C 
compilation, and Ipp for PC version at C++ compilation. 


2. The compiler automatically generates according to the option. 
3. Extension becomes p for C compilation and pp for C++ compilation. 


1.3.3 Compiler Options 


Table 1.2 shows compiler option formats, abbreviations, and defaults. Characters underlined 
indicate the minimum valid abbreviation. Bold characters indicate default assumptions. 


"C" or "C++" in the parentheses indicates that the valid option for C compilation and C++ 
compilation respectively. "SH1," "SH2," "SH2E," "SH3," "SH3E," and "SH4" in the brackets 
indicate to which option CPU type they are valid. 


Note: Options without an asterisk are supported in Ver. 5.0. Those with an asterisk are 
supported in Ver. 5.1 or later. 
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Table 1.2 Compiler Options 


Item Format Suboption Specification 
CPU type cpu = shi | SH-1 object is generated. 
(C, C++) ho reser 
ISH1 to SH4] Ss | SH-2 object is generated. 
sh2e | SH-2E object is generated. 
sh3 | SH-3 object is generated. 
sh3e_ | SH-3E object is generated. 
sh4 SH-4 object is generated. 
Optimization optimize = 0 | Object without optimization is 
(C, C++) output. 
[SH1 to: SHA] 1 Object with optimization is output. 
Optimization speed Optimization in execution speed. 
on speed= shift* Develops the shift operation in 
[SH1 to SH4] higher-speed object code. 
loop* | Develops the loop statements in 
higher-speed object code. 
switch* | Develops the switch statements 
in higher-speed object code. 
struct* Performs direct inline expansion 
of structures, and assignment 
statements of class type and 
double type to the code. 
nospeed Optimization in balance between 
execution speed and program 
size is selected. 
size Optimization in program size is 
selected. 
Debugging debug Output 
information 
(C, C++) nodebug No output 
[SH1 to SH4] 
Listing format show = source | nosource | Source list yes/no 
(C, C++) ; ; es 
[SH1 to SH4] object | noobject | Object list yes/no 
statistics | nostatistics | Statisticsinformation yes/no 
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Table 1.2 


Item 


Listing format 
(C, C++) 
[SH1 to SH4] 
(cont) 


Listing file 
(C, C++) 
[SH1 to SH4] 


Object file 
(C, C++) 
[SH1 to SH4] 


Object program code = 


format 
(C, C++) 
[SH1 to SH4] 


Macro name 
(C, C++) 
[SH1 to SH4] 


Include file 
(C, C++) 
[SH1 to SH4] 


Section name 
(C, C++) 
[SH1 to SH4] 


Compiler Options (cont) 


Format Suboption 


show = include | noinclude | 
expansion | noexpansion | 
allocation* | noallocation* | 
width = <numeric value> | 


length = <numeric value> 


listfile [ = <list file name>] 


nolistfile 


objectfile = <object file name> 


machinecode | 


asmcode 

define = = _<macroname>=<name>_ | 
<macro name> = <constant> | 
<macro name> 

include = <path name> 

section= program = <section name> | 


const = <section name> | 
data = <section name> | 


bss =<section name> 
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Specification 


List after include expansion 
yes/no 


List after macro expansion 
yes/no 


Symbol allocation information 
yes/no 


Maximum characters per line: 
0, 80 to 132 (default: 132) 


Maximum lines per page: 
0, 40 to 255 (default: 80) 


Output 
No output 


Output 


Program in machine language is 
output. 


Assembly source program is 
output. 


<name> is defined as 
<macro name>. 


<constant> is defined as 
<macro name>. 


<macro name> is assumed to be 
defined. 


Include file destination path name 
is specified (multi-specification is 
possible). 

Program area section name is 
specified. (default: P) 


Constant data area section name 
is specified. (default: C) 


Initialized data area section name 
is specified. (default: D) 


Non-initialized data area section 
name is specified. (default: B) 
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Table 1.2 Compiler Options (cont) 


Item Format Suboption 


Help message _ help 
(C, C++) 
[SH1 to SH4] 


Program section pic= 0 || 
position 
independent 
(C, C++) 
[SH2 to SH4] 


Area of string _—_ string = const 
literal to be 
output 

(C, C++) 
[SH1 to SH4] 


Comment comment = nest 
nesting 

(C, C++) 
[SH1 to SH4] 


Japanese code euc 
select in string 
literals 

(C, C++) 

[SH1 to SH4] 


data 


nonest 


sjis 


Subcommand  subcommand= <file name> 


file select 
(C, C++) 
[SH1 to SH4] 
Division division = cpu | 
operation : 
(C, C++) peripheral | 
[SH2] 
nomask 
Byte order endian = big | 
(C, C++) little 


[SH3 and SH4] 
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Specification 
Output 


Generates no position 
independent codes for the 
program section 


Generates position independent 
codes for the program section 


String literal is output to constant 
section (C). 


String literal is output to initialized 
data section (D). 

Permits comment (/* */) nesting. 
Does not permit comment (/* */) 
nesting. 

Selects euc code. 


Selects sjis code. 


Includes command option from a 
file specified by <file name>. 


Uses CPU's division instruction. 


Uses a divider (with masking 
interruption). 


Uses a divider (without masking 
interruption). 


Specifies big endian. 


Specifies little endian. 


Table 1.2 Compiler Options (cont) 


Item 


Inline expansion 
(C, C++) 
[SH1 to SH4] 


Default header 
file 

(C, C++) 

[SH1 to SH4] 


MACH and 
MACL registers 
(C, C++) 

[SH1 to SH4] 


Information 
message output 
(C, C++) 

[SH1 to SH4] 


Label 16-byte 
alignment 

(C, C++) 
[SH1 to SH4] 


Double type to 

single precision 
(C, C++) 

[SH1 to SH3E] 


Japanese 
character 
conversion 
(C, C++) 
[SH1 to SH4] 


Format 


inline 


inline = 


noinline 


preinclude = 


macsave = 


message 


nomessage 


aligni6 


noalign16 


double = 


outcode = 


Suboption 


<numeric value> 


<file name> 


float 
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Specification 


Performs inline expansion 
automatically. 


Specifies the maximum size of a 
function to expand where the 
function is called. 


Does not perform inline 
expansion automatically. 


Includes contents of a specified 
file at the beginning of 
compilation units. 


Does not guarantee contents of 
MACH and MACL registers at 
function call. 


Guarantees contents of MACH 
and MACL registers at function 
call. 


Outputs information message. 


Does not output information 
message. 


Labels placed immediately after 
an unconditional branch 
instruction other than a 
subroutine call in a program 
section must be aligned in 16 
bytes. 


Does not place labels aligned in 
16 bytes. 


Treats double type (double 
precision floating point number) 
as float type (single precision 
floating point number) when 
generating object. 


Selects euc code. 


Selects sjis code. 
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Table 1.2 


Item 


ABS16 
declaration 
(C, C++) 
[SH1 to SH4] 


Loop unroll 
(C, C++) 
[SH1 to SH4] 


Inline expansion nestinline = 


(C, C++) 
[SH1 to SH4] 


Extension of 
return value 
(C) 

[SH1 to SH4] 


Preprocessor 
inline output 
(C, C++) 
[SH1 to SH4] 


Browser 
information 
(C++) 

[SH1 to SH4] 


Compiler Options (cont) 


Format Suboption 
abs16 = run | 
all 
loop 
noloop 


<numeric value> 


rtnext 


nortnext 


preproccessor  [=<file name>] 


browser 


Embedded C++ ecpp* 


language 
(C++) 
[SH1 to SH4] 


ISO-Latin 1 code latin1* 


support 

(C, C++) 
[SH1 to SH4] 
FPU 

(C, C++) 
[SH4] 


De-normalized 


numbers 
(C, C++) 
[SH4] 


fpu= single . | 
double 


denormalization=off —| 
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Specification 


Assumes all execution routines to 
have been declared with 
#pragma abs16. 


Generates all label addresses in 
16 bits. 


Optimizes loop unrolling. 


Does not optimize loop unrolling. 


Specifies the number of times to 
expand nested inline functions. 


Creates a sign-extension or zero- 
extension of the return value 


Creates no sign-extension or 
zero-extension of the return value 


Source program after 
preproccessor expansion is 
output. 


Output 


Checks compiled results 
according to the embedded C++ 
language specifications 


Compiles string line literals, 
comments, and character 
constants as ISO-Latin1 codes 


Processes floating-point 
operation in single precision 


Processes floating-point 
operation in double precision 


Processes de-normalized 
numbers as zeros 


Processes de-normalized 
numbers as they are 


Table 1.2 


Item 


Rounding 
direction 

(C, C++) 

[SH4] 


Compiler Options (cont) 


Format Suboption 
round= zero | 


nearest 


Switch statement case= ifthen* — | 


development 
method 

(C, C++) 
[SH1 to SH4] 


table * 


External variable volatile* 


optimization 
(C, C++) 
[SH1 to SH4] 


Packed 
structure 

(C, C++) 
[SH1 to SH4] 


Inter-module 
optimization 
(C, C++) 
[SH1 to SH4] 


Language 
selection 

(C, C++) 
[SH1 to SH4] 


novolatile* 


pack* 


goptimize* 


lang= c | 
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Specification 
Rounds to zero 


Rounds to nearest 


Develops switch statements by 
the if_then method 


Develops switch statements by 
the table method 

Does not optimize all the external 
variables as volatile 


Optimizes external variables that 
is not declared as volatile 
statement 


Sets boundary alignment number 
of structure and class types to 1 


byte 


Outputs inter-module optimizing 
information 


Compiles according to C syntax 


Compiles according to C++ 
syntax 


Rev. 1.0, 09/98, page 11 of 476 


(1) CPU Type (C, C++) 

-cpu=sh1|sh2|sh2e|sh3|sh3e|sh4 
This option specifies the target CPU. 
cpu=sh1 generates object for SH-1. 
cpu=sh2 generates object for SH-2. 
cpu=sh2e generates object for SH-2E. 
cpu=sh3 generates object for SH-3. 
cpu=sh3e generates object for SH-3E. 
cpu=shé4 generates object for SH-4. 


A library to be linked differs according to a CPU. For details, refer to section 1.3.5, 
Correspondence to Standard Libraries. 


The default of this option is cpu=sh1. 


(2) Optimization Level (C, C++) 
-optimize=0|1 
Specifies compiler optimization. 
When opt imize=0 is specified, the compiler does not optimize the object program. 
When opt imize=1 is specified, the compiler optimizes the object program. 


The default of this option is opt imize=1. 


(3) Optimization select (C, C++) 
-speed 
Performs speed priority optimization. If speed option is specified, program execution 
speed is improved but program size may increase. 
The default of this option is speed=shift, loop, switch, struct. 
-speed=shift 
Develops the shift operations in higher-speed object codes. 
-speed=loop 
Develops the loop statement in higher-speed object codes. 
-speed=switch 
Develops the switch statements in higher-speed object codes. 
-speed=struct 
Performs the inline expansion of structures and assignment statements of class and 
double types to the object codes. 
-nospeed 
If nospeed is specified but size is not specified, balanced optimization of execution 
speed and program size is performed. 
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-size 
This option specifies optimization in object size. 
The default of this option is nospeed. 


(4) Debugging information (C, C++) 

=debug 
Outputs debugging information necessary for source level debugging into object files. 
If the object format is specified as machine language, the debugging information is 
output directly. When assembly source program is specified as output, the .LINE 
directive is output into the assembly source program, so that the assembly source 
program can be executed in steps of C source level. At C++ compile, a directory 
cppdtb is created under the object file and a browser information file with the extension 
dtb is generated in the directory. However, the browser information file contains only 
declaration/definition information, so browsing of statements and/or 
declaration/definition alone is possible. To browse entire contents of C++ source 
programs, specify the browser option. 

-nodebug 
If nodebug is specified, debugging information is not output in the object file. 
The default of this option is nodebug. 


(5) List contents and format (C, C++) 


-show=source | nosource| object |noobject |statistics|nostatistics 
| include |noinclude|expansion|noexpansion|allocation 
|noallocation|width=<numeric value>|length=<numeric value> 


Specifies the output format of list files. This option is valid when the listfile 
option is specified. 

show=source outputs a list of source programs 
show=nosource outputs no list of source programs 
show=object outputs a list of object programs 

show=noobject outputs no list of object programs 
show=statistics outputs a list of statistical information 
show=nostatistics outputs no list of statistical information 
show=include outputs a list of developed results of include 
show=noinclude outputs no list of developed results of include 
show=expansion outputs a list of developed results of macro 
show=noexpansion outputs no list of developed results of macro 
show=allocation outputs a list of symbol allocation information 


show=noallocation outputs no list of symbol allocation information 
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In show=width=<numeric values, the number specified by the <numeric 
value> is set as the maximum number of characters in a single line. The <numeric 
value> can specify numbers from 80 to 132 or 0. 


In show=length=<numeric values, the number specified by the <numeric 
value> is set as the maximum number of lines on a single page. The <numeric value> 
can specify numbers from 40 to 255 or 0. 

If show=width=0 or show=length=0 is specified, following interpretations will 
apply: 

If show=width=0 is specified, all the characters between two carriage return codes 
are taken as a single line. 


If show=length=0 is specified, no limit is set for the number of lines per page, and 
no page end is set up. 


(6) List file (C, C++) 
-listfil [=<list file name>] 


Outputs a list file. If no file name is specified, a list file with the same file name as the 
source file with a standard extension (lis/Ist/lpp) is created. The standard extension for 
UNIX version is lis, that for PC version at C compilation is Ist, and that for PC version 
at C++ compilation is Ipp. 


-nolistfile 
Outputs no list file. 
The default of this option is nolistfile. 


(7) Object file (C, C++) 
-objectfile=<file name> 


Specifies the name of the output object file. If no <file name> is specified, Outputs a 
file with the same file name as the source file with a standard extension obj (when 
object format is machine language program) or src (when object format is assembly 
source program). 


(8) Object code (C, C++) 
-code=machinecode | asmcode 
Specifies output of machine language object files or assembly source files. 


code=machinecode outputs machine language programs that can be input to the 
inter-module optimizer. 


code=asmcode outputs assembly source programs that can be input to an assembler. 


If code=asmcode and debug are specified, the .LINE directive is output in 
assembly source programs. However, the output files cannot be browsed. 


The default of this option is code=machinecode. 
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(9) Macro name definition (C, C++) 


-define=<macro name>=<name>|<macro name>=<constant> 
|<macro name> 


Validates the macro definition specified by this option at the beginning of a source 
program. The macro name, name, and constant length must be specified within 31 
characters each. If excess characters are specified, the first 31 characters are used. 


With the use of this option, macro definitions similar to that in source programs can be 
specified in the command line option. 


Table 1.3 shows the specifications of the macro name that can be specified by the 
option. 


Table 1.3. Macro Names, Names, and Constants Specified by the Define Option 


Item Description 


Macro name A string literal beginning with a letter or an underscore followed by zero or more 
| letters, underscores, and numbers. 


Name A string literal beginning with a letter or an underscore followed by zero or more 
letters, underscores, and numbers. 


Constant Decimal constant: A string literal of one or more numbers (0 to 9), ora 
| string literal of one or more numbers followed by a 
period (.) followed by zero or more numbers. 


Octal constant: A string literal that begins with a zero followed by 
one or more numbers (0 to 7). 


Hexadecimal constant: A string literal that begins with a zero followed by an 
x, then followed by one or more numbers or 
alphabetical letters (A to F). 


(10) Include File (C, C++) 
-include=<path name> 


Specifies a directory where an include file is searched for. For details on how to search, 
refer to Appendix A.1 (13), Preproccessor. 


(11) Section Name (C, C++) 


-section=|program=<section name>|const=<section name> 
|data=<section name>|bss=< section name > 


Changes the section name of an object program. The <section name> must be alphabet, 
number, or underlined characters, however, the first character must not be a numeral. 
The section name must be specified within 31 characters. If excess characters are 
specified, the first 31 characters are used. 
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The default section names are as follows: P for the program area section, C for the 
constant area section, D for the initialized data area section, and B for the non- 
initialized data area section. The sections whose names cannot be changed are D_INIT_ 
for the initialized processing data area section, D_END_ for the post-processing data 
area section, and C_$VTBL for the virtual function table area. 


(12) Help Message (C, C++) 
-help 


Displays a list of compiler options. Once this option is specified, the other option(s) 
will be ignored. 


(13) Position Independent (C, C++) 
-pic=0|1 

When pic=1 is specified, a program section after linking can be allocated to any 
address and executed. A data section can only be allocated to an address specified at 
linking. When using this option as a position independent code, a function address 
cannot be specified as an initial value. At C++ compilation, a pointer to a virtual 
function or function member requires a function address as the initial value. Therefore, 
C++ programs containing virtual functions and pointers to member functions cannot be 
executed as position independent codes. Note that if cpu=sh1 is specified, pic=1 is 
ignored. A library to be linked varies according to the cpu, pic, endian, or 
double option. For details, refer to section 1.3.5, Correspondence to Standard 
Libraries. 


Example 1 
extern int f (); 


int (*fp)() = £; <-- Cannot be specified 


Example 2 

struct A {virtual void £();}; <-- Cannot be specified 
void (A::*ap)() = &A::£; <-- Cannot be specified 
The default of this option is pic=0. 


(14) String output area (C, C++) 
-string=const|data 
Specifies to which section strings are output, either the constant area section (C) or 
initialized data area section (D). 
When string=const is specified, string literals are output to constant data area 
section (C). When string=data is specified, string literals are output to initialized 
data area section (D). 


The default of this option is string=const. 
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(15) Comment Nesting (C, C++) 
-comment=nest |nonest 
Specifies whether or not to permit comment /* */ nesting. 
Example 
/* comment 


int a; /* nestl /* nset2 */  */ 


*/ 

When comment =nest is specified, an underlined section is treated as a nested 
comment and the outermost comment is enforced. 

When comment=nonest is specified, a comment is treated to end by nest2*/. 
Therefore, a section after nest2*/ is treated as an error. 


The default of this option is comment=nonest. 


(16) Japanese code select in string literals (C, C++) 
-eue 
Selects euc for the Japanese code for string literals in program. 
=sj1s 
Selects sjis for the Japanese code for string literals in program. 


When this option is omitted, euc or sjis is selected according to the host computer. For 
details, refer to section 2.3.5, Japanese Description in String Literals. 


(17) Subcommand file select (C, C++) 
-subcommand=<file name> 


Assumes contents of a specified file name as an option. This option can be specified in 
a command line more than once. In a subcommand file, parameters must be delimited 
by a space, a carriage return, or a tab. Contents of a subcommand file will be expanded 
to an area specified by a subcommand in a command line parameter. A subcommand 
option cannot be specified in a subcommand file. 


Example: The following examples are the same as shc -debug -cpu=sh2 
test..c¢. 


Command line 

she -sub=test.sub test.c 
Contents of test.sub 

-debug 

-cpu=sh2 
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(18) Division Operation (C, C++) 

-division=cpu| peripheral |nomask 
Selects execution routines for integer type division and residue. 

-division=cpu 
Selects the execution routine by the DIV1 instruction. 

-division=peripheral 
Selects the execution routine that uses the divider. (Sets interrupt mask level to 15.) 
Executable only if cpu type is SH2. 

-division=nomask 
Selects the execution routine that uses the divider. (No change in interrupt mask level.) 
Executable only if cpu type is SH2. 
When specifying peripheral or nomask, note the following: 
(1) Division by 0 is not checked and errno is not set up. 


(2) When nomask is specified, if an interrupt occurs during operation of the divider, 
and if the divider is used in the interrupt process routine, the result is not 
guaranteed. 


(3) Overflow interrupt is not supported. 


(4) Results of division by zero and overflow depend on specifications of the divider, 
and may differ from the results obtained when cpu is specified. 


The default of this option is division=cpu. 


(19) Memory byte order (C, C++) 
-endian=big|little 
This option can be combined with any cpu option. 
endian=big Arranges data bytes in the Big Endian order. 
endian=little Arranges data bytes in the Little Endian order. 


Little endian object programs do not run on SH1, SH2, and SH2E. Different libraries 
must be linked depending on the cpu, pic, endian, and double options. For 
details, see section 1.3.5, Correspondence to Standard Libraries. 


The default of this option is endian=big. 


(20) Inline expansion (C, C++) 


-inline,-inline=<numeric value>,-noinline 


Specifies whether to automatically perform inline expansion of functions. 
-inline 


Performs inline expansion. 
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-inline=<numeric value> 


Specifies the maximum number of nodes of functions (total number of words such as 
variables and operators except for the declaratives) for which inline expansion should 
be performed. 


-noinline 
Does not perform inline expansion. 


If the speed option is specified, the default of this option is inline=20. Ifthe 
nospeed option, size option, or opt imize=0 option is specified, the default of 
this option is noinline. 


(21) Default header file (C, C++) 
-preinclude=<file name> 


Includes the specified file contents at the beginning of a compilation unit. Specify the 
<file name> by a relative path from the directory where you started the compiler, or by 
an absolute path. 


(22) MACH and MACL registers (C, C++) 
-macsave=0|1 

Specifies whether to guarantee that the contents of MACH and MACL registers remain 
unchanged after a function is called. 
macsave=0 
Contents of MACH and MACL registers may change after a function is called. 
macsave=1 
Contents of MACH and MACL registers remain unchanged after a function is called. 


Functions compiled under macsave=0 cannot be called from functions compiled 
under macsave=1. On the contrary, functions compiled under macsave=1 can be 
called from functions compiled under macsave=0. 


The default of this option is macsave=1. 
(23) Information message output (C, C++) 


-message 
Outputs information messages. 
-nomessage 
Does not output information messages. 


The default of this option is nomessage. 


(24) Label 16-byte alignment (C, C++) 
-alignl16é 
Aligns every label within the program section that is placed immediately after an 


unconditional branch instruction except for subroutine call to a 16-byte boundary. 
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-noalignl16 


Does not make 16-byte alignment of labels that are placed immediately after an 
unconditional branch instructions except for subroutine call. 


(25) Double type to single precision (C, C++) 
-double=float 


Treats double precision type floating-point values as single precision type floating-point 
values when generating object code. 


(26) Japanese character conversion (C, C++) 
-outcode=euc|sjis 
Use this option to specify Japanese kanji character code to be output to object program 
for Japanese language written in a string literal or a character constant. 
outcode=euc Uses the euc kanji character code. 


outcode=sjis Uses the sjis kanji character code. 


(27) ABS16 declaration (C, C++) 
-abs16=run|all 
abs16=run 
Assumes all the execution routines to have been declared with #pragma abs 16. 
abs16=all 


Generates every label address in 16 bits. 


(28) Loop unrolling (C, C++) 
-loop, -noloop 
Specifies whether to optimize loop unrolling. 
-loop 


Gives priority to execution speed when coding loop statements (for, while, and do- 
while). 


-noloop 


Does not give priority to execution speed when coding loop statements (for, while, and 
do-while). 
The default of this option is noloop. 


(29) Inline coding (C, C++) 
-nestinline=<numeric value> 


Specifies the number of times of inline expansion of nested inline functions. Up to 16 
can be specified. The default of this option is nest line=1. 
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Example 
Source program 
#pragma inline (funl, fun2, fun3) 
extern int dat; 
void funl() {at++; } 
void fun2() {funl1();} 
void fun3() {fun2();} 


(1) Inline expansion image for nestinline=1 
#pragma inline (funl1, fun2,fun3) 
extern int dat; 
void funl() {a++; } 
void fun2() {a++;} 


void fun3() {£1();} 


(2) Inline expansion image for nestinline=2 
#pragma inline (funl,fun2,fun3) 
extern int dat; 
void funl1() {a++;} 
void fun2() {at++; } 


void fun3() {a++;} 


(30) Extension of return value (C) 

crtnext, -nortnext 
Specifies whether to perform sign/zero extension in function return value register RO 
for a return statement that returns an (unsigned) char type or (unsigned) short type 
value. This option need not be specified if function prototype is declared. 

-rtnext 
Performs sign/zero extension for the function return value. 

-nortnext 
Does not perform sign/zero extension for the function return value. 


The default of this option is nortnext. 
(31) Preprocessor expansion output (C, C++) 


-preprocessor [=<file name>] 
Outputs source program that has been processed by the preprocessor. If no file name is 
specified, an output file with the same file name as the source file with a standard 
extension is created. The standard extension at C compilation is p, and that at C++ 
compilation is pp. 
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(32) Browser information (C++) 


-browser 
Outputs necessary browser information and debugging information for the browser. At 
C++ compilation, if a directory cppdtb is absent under the object file output directory, 
the compiler creates directory cppdtb and generates browser information files under this 


directory. 


(33) Embedded C++ (C++) 
-ecpp 
Checks for syntax error of a C++ program according to embedded C++ language 
specifications. 


(34) ISO-Latin1 code support (C, C++) 
-latinl 
Interprets string literals, comments, and character constants as ISO-Latin1 code. 


(35) FRU (C, Cr?) 
-fpu=single|double 
fpu=single 
Carries out all floating point calculations at single precision. 
fpu=double 
Carries out all floating point calculations at double precision. 
This option takes effect only if cpu type is SH-4. 
When the program has no floating point calculations, specify fpu=single. 


(36) Denormalization (C, C++) 
-denormalization=off|on 
-denormalization=off Treats denormalized numbers as zeros. 
-denormalization=on Treats denormalized numbers as they are. 
This option takes effect only if cpu type is SH-4. 
The default of this option is denormalization=off. 


(37) Rounding direction (C, C++) 
-round=zero|nearest 
round=zero Rounds to zero. 
round=nearest Rounds to nearest. 
This option takes effect only if cpu type is SH-4. 


The default of this option is round=zero. 
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(38) Switch statement handling (C, C++) 
-case=ifthen|table 

case=ifthen 
Handles a switch statement in if_then construct. The if_then construct compares the 
evaluation value of the switch statement and the value of a case label, and if the values 
match, goes to the case label statement. This process is iterated as many times as the 
number of case labels. Object code size of an if_then construct increases as the switch 
statement contains more case labels. 


case=table 


Handles a switch statement by table lookup. Table lookup saves the destinations from a 
case label on a jump table, and goes to the case label statement that corresponds to the 
evaluation result of a switch statement by a single reference to the table. Although the 
size of the jump table which is stored in the constant area increases as the switch 
statement contains more case labels, execution speed remains constant. 


If this option is not specified but the speed or size option is specified, the compiler 
automatically selects either if_then construct or table lookup giving priority to either 
speed or size. 


(39) External variable optimization (C, C++) 
-volatile, -novolatile 
-volatile Does not optimize external variables. 
-novolatile Optimizes external variables. 


The default of this option is novolatile. 


(40) Packed structure (C, C++) 
-pack 
Aligns structure type, union type, and class type objects to 1-byte boundaries. 


(41) Inter-module optimization (C, C++) 
-goptimize 
Outputs inter-module optimization additional information. 


If this option is specified but a directory shiop is absent under the object program 
output directory, the compiler creates directory shiop and generates inter-module 
optimization additional information files under this directory. 


(42) Language (C, C++) 
-lang=c| cpp 
This option selects language. 
lang=c Observes C syntax when compiling. 
lang=cpp Observes C++ syntax when compiling. 
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If this option is not specified, either C or C++ syntax is observed depending on the 
extension of the source file name. Only the shc command can be used to invoke the 
compiler. 


1.3.4 Option Combinations 


If a pair of conflicting options or suboptions are specified for a file, only one of them is considered 
valid. Table 1.4 shows such option combinations. 


Table 1.4 Option Combinations 


Valid Option Invalid Option 
nolist show 
code = asmcode* debug* 


show = object 


help All other options 

cpu = sh1 pic = 1 

optimize = 0 loop 

cpu= sh4 double = float (fpu = single is assumed) 
cpu= other than sh4 fpu=single | double 

cpu= other than sh4 denormalize=on | off 

cpu= other than sh4 round=nearest | zero 


Note: When debug option is specified during assembly source output, a .LINE directive is 
embedded in the output code. A .LINE directive gives C/C++ language source line 
information to a debugger. After that, C/C++ language source lines are displayed for 
debugging. However, C/C++ language level debugging is not performed for variable 
values. 


1.3.5 Correspondence to Standard Libraries 


Standard libraries of 74 types are supported. Link libraries listed in Table 1.5 that fit the cpu, 
pic, endian, double, fpu, denormalization and round options you have specified. 
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Table 1.5 


Library name 


shclib.lib 
shclibf.lib 
shcnpic.lib 
shcpic.lib 
shenpicf.lib 
shcpicf.lib 
shc2enp.lib 
shc2ep.lib 
shc2enpf.lib 
she2epf.lib 
shc3npb.lib 
shc3pb.lib 
shc3npl.lib 
shc3pl.lib 
shc3npbf.lib 
shc3pbf.lib 
shc3nplif.lib 
shce3plf.lib 
shcenpb.lib 
shcepb.|ib 
shcenpl.lib 
shcepl.lib 
shcenpbf.lib 
shcepbf.lib 
shcenplf.lib 
shceplf.lib 
sh4nbmzz.lib 
sh4pbmzz.lib 
sh4nlmzz.lib 
sh4plmzz.lib 
sh4nbmdz.lib 


oO;}—m>}] oO}; >] OF] Am} OF] Am] oy} my Oy mY] Oy mY] Oy mY] Oy my Oy ms] Oy met Oy ms] Oy] Amy Oy] AK] Oo 


endian 


big 
big 
big 
big 
big 
big 
big 
big 
big 
big 
big 
big 


Compiler Option 


little _ 
little — 


big 
big 


little — 
little — 


big 
big 


little = 
little _ 


big 
big 


little — 
little — 


big 
big 


little off 
little off 


big 
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denormal 


round fpu 


Correspondence of Standard Libraries and Compilation Options 


double=float 
— No 
— Yes 
— No 
— No 
— Yes 
— Yes 
—_ No 
— No 
— Yes 
— Yes 
— No 
— No 
— No 
— No 
— Yes 
a Yes 
— Yes 


— Yes 
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Table 1.5 Correspondence of Standard Libraries and Compilation Options (cont) 


Compiler Option 


Library name-_ cpu pic endian denormal round fpu double=float 
sh4pbmdz.lib = sh4 1 big on zero No — 
sh4nimdz.lib sh4 0 little on zero No — 
sh4plmdz.lib sh4 1 little on zero No — 
sh4nbmzn.lib sh4 0 big off nearest No — 
sh4pbmzn.lib sh4 1 big off nearest No — 
sh4nimzn.lib sh4 0 little off nearest No — 
sh4plmzn.lib sh4 1 little off nearest No — 
sh4nbmdn.lib sh4 0 big on nearest No — 
sh4pbmdn.lib sh4 1 big on nearest No = 
sh4nimdn.lib sh4 0 little on nearest No — 
sh4plmdn.lib sh4 1 little on nearest No — 
sh4nbfzz.lib sh4 0 big off zero single — 
sh4pbfzz.lib sh4 1 big off zero single — 
»sh4nifzz.lib sh4 0 little off zero single — 
sh4plfzz.lib sh4 1 little off zero single —_— 
sh4nbfdz.lib sh4 0 big on zero single — 
sh4pbfdz.lib sh4 1 big on zero single — 
sh4nlfdz.lib sh4 0 little on zero single — 
sh4plfdz.lib sh4 1 little on zero single — 
sh4nbfzn.lib sh4 0 big off nearest single — 
sh4pbfzn.lib sh4 1 big off nearest single — 
sh4nifzn.lib sh4 0 little off nearest single — 
sh4plfzn.lib sh4 1 little off nearest single — 
sh4nbfdn.lib sh4 0 big on nearest _ single — 
sh4pbfdn.lib sh4 1 big on nearest single — 
sh4nifdn.lib sh4 0 little on nearest single — 
sh4plfdn.lib sh4 1 little on nearest _ single — 
sh4nbdzz.lib sh4 0) big off zero double — 
sh4pbdzz.lib sh4 1 big off zero double — 
sh4nidzz.lib sh4 0 little off zero double — 
sh4pldzz.lib sh4 1 little off zero double — 
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Table 1.5 Correspondence of Standard Libraries and Compilation Options (cont) 


Compiler Option 


Libraryname cpu pic — endian’ denormal round fpu _—double=float_ 
sh4nbddzlib sh4 0 big on zero. double — 
sh4pbddz.lib sh4 1 big on zero double — 
sh4nlddz.lib sh4 0 little on zero double — 
sh4plddz.lib sh4. 1 litle on | zero double — | 
sh4nbdznlib sh4 0 big off nearest double — _ 
sh4pbdznlib sh4. 1 big off nearest double —  _ 
sh4pldznlib sh4 1 litle | off nearest double —  _ 
sh4nbddnlib sh4. 0 big on nearest double — 
sh4pbddn.lib sh4 1 big on nearest double — 
sh4niddnlib sh4  O litle | on ‘nearest double — 
sh4plddn.lib sh4 1 little on nearest double — 
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1.3.6 Compiler Listings 

This section describes compiler listings and their formats. 

(1) Structure of Compiler Listings 

Table 1.6 shows the structure and contents of compiler listings. 


Table 1.6 Structure and Contents of Compiler Listings 


Option Specification 


List Structure Contents Method*' Default 

Source listing Listing consists of source programs show=[no]source No output 
Source program listing after include file (show=[noJinclude)*? —_ No output 
and macro expansion (show=[no]expansion) 

Object listing Machine language generated by the show=[no]object Output 


compiler and assembly code 


Statistics Total number of errors, number of show=[no]statistics Output 
source program lines, size of each 
section (byte), and number of symbols 


Command line File names and options specified in the — Output 
specification command line 


Notes: 1. All options are valid when listfile is specified. 
2. The option enclosed in parentheses is only valid when show=source is specified. 
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(2) Source Listing 


The source listing can be output in two ways. When show=noinclude,noexpansion is 
specified, the unpreprocessed source program is output. When show=include, expansion is 
specified, the preprocessed source program is output. Figures 1.3 and 1.4 show examples of these 
output formats. Bold characters in figure 1.4 show the differences. 


ke RKKEKK SOURCE LISTING **** KR KKK KKK 
FILE NAME: m0260.c 


File Line O----4+----1----4----2----4+----3----4+----4----4+----5--- 
mO260. #include "header.h" 
mO260. 
m0260. int sum2 (void) 
mO0260. 


mO260. 


{ int j; 


mO260. 
m0260. 
mO260. 


#ifdef SMALL 
j=SML_INT; 


Cc 
Cc 
c 
Cc 
Cc 
c 
Cc 
¢ 


#else 
j=LRG_INT; 
#endif 


mO260. 


Q 


mO260. 


Q 


m0260. 
mO0260. return j;/* continuel23456789012345678901234567 
(2) +2345678901234567890 */ 
(7) 


Q 


Figure 1.3 Source Listing Output for show = noinclude, noexpansion 
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KKK KEKKKKKEK SOURCE LISTING RREKEKEKKKKKKKEK 


FILE NAME: m0260.c 


Seq File i Q----+----1----+----2----+----3----+----4----+----5--- 
m0260.c #include "header.h" 

header.h #define SML_ INT 

header.h #define LRG INT 

m0260. 

mO260. int sum2 (void) 

m0260. { int 4; 

m0260. 

m0260. #ifdef SMALL 

mO260. j=SML_INT; 


dL, 
2 
3 
4 
5 
6 
7 
8 


PP 
oOo Wo 


m0260. #else 
m0260. j=100; 
m0260. #endif 
mO260. 


PoP PR 
Ww nN BP 


m0260. return j;/* continuel23456789012345678901234567 
+2345678901234564890 */ 


(7) 


Figure 1.4 Source Listing Output for show = include, expansion 
Description: 


(1) Listing line number 
(2) Source program file name or include file name 
(3) Line number in source program or include file 


(4) Source program lines resulting from an include file expansion when show=include is 
specified. 


(5) Source program lines that are not to be compiled due to conditional compile directives such as 
#ifdef and #elif being marked with an X when show=expansion is specified. 

(6) Source program lines containing a macro expansion #define directives being marked with an E 
when show=expansion is specified. 


(7) If a source program line is longer than the maximum listing line, the continuation symbol (+) is 
used to indicate that the source program line is extended over two or more listing lines. 
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(3) Object Listing 


The object listing can be output in two ways. When show=source, object is specified, the 
source program is output. When show=nosource, object is specified, the source program is 
not output. 


Figures 1.5 and 1.6 show examples of these listings. 
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REKKKKKKKKKK OBJECT LISTING KRRKKKKKKKKEKEK 


FILE NAME: m0251.c 


SCT OFFSET CODE C LABEL INSTRUCTION OPERAND COMMENT 
(1) (2) (3) (4) (5) 
m0251.c 1 extern int multipli(int); 
mo251.u:¢ 2 
mO251.c 3 int multipli(int x) 
P 00000000 _multipli: ; function: multipli 
; frame size=16 (7) 
; used runtime library name: 
;_muli (8) 
00000000 4F22 sTs.L PR,R15 
00000002 7FF4 ADD #-12,R15 
00000004 1F42 MOV.L R4,@(8,R15) 
m0251.c 4 { 
mO251.c 5 me ds 
m0251.c 6 int j5 
m0251.c 7 
mO251.c 8 j=1; 
00000006 E201 MOV #1,R2 
00000008 2F22 MOV.L R2,@R15 
m0251.c 9 for (i=1;i<=x;i++) { 
O000000A £301 MOV #1,R3 
0000000C 1F31 MOV.L R3,@(4,R15) 
0000000E aAoo9g BRA L213 
00000010 0009 NOP 
00000012 L214: 
mO0251.c 10 j*=i; 
00000012 50F1 MOV.L @(4,R15) ,RO 
00000014 61F2 MOV @R15,R1 
00000016 D30A MOV.L L216+2,R3 7 _muli 
00000018 430B JSR @R3 


Figure 1.5 Object Listing Output for show = source, object 
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kkk RRR KKEKEK OBJECT LISTING **** ee KKK KEK 
FILE NAME: m0251.c 
SCT OFFSET CODE C LABEL INSTRUCTION OPERAND COMMENT 


(1) (2) (3) (4) (5) 
P ;File m0251.c ,Line 3 ; block 


00000000 _multipli: (6) ; function: multipli 


; frame size=16 (7) 
; used runtime library name: 
i muli (8) 
00000000 PR,@R15 
00000002 #-12,R15 
00000004 R4,@(8,R15) 
,Line 4 ; block 
,Line 8 ; expression statement 
00000006 #1,R2 
00000008 R2,@R15 
,Line 9 
0000000A #1,R3 
0000000C R3,@(4,R15) 
OOO00000E L213 
00000010 
00000012 
,Line 9 ; block 
,Line 10 ; expression statement 
00000012 @(4,R15) ,RO 
00000014 @R15,R1 
00000016 L216+2,R3 ;__muli 
00000018 @R3 


Figure 1.6 Object Listing Output for show = nosource, object 
Description: 


(1) Section attribute (P, C, D, B, D_LINIT_, DLEND_, and C_SVTBL) of each section 
(2) Offset address relative to the beginning of each section 

(3) Contents of the offset address of each section 

(4) Assembly code corresponding to machine language 


(5) Comments corresponding to the program (only output when not optimized; however, labels are 
always output) 


(6) Line information of the program (only output when not optimized) 
(7) Stack frame size in bytes (always output) 
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(8) Routine name that is being executed 
(4) Statistics Information 


Figure 1.7 shows an example of statistics information. 


week eK STATISTICS INFORMATION *******x 


kkk kee PRROR INFORMATION ******* eX 
NUMBER OF ERRORS: 

NUMBER OF WARNINGS: 

NUMBER OF INFORMATIONS : 


#RERRERK SOURCE LINE INFORMATION ***#*#%#%% 


COMPILED SOURCE LINE: 


RREAEKEX SECTION SIZE INFORMATION *¥****%% 


PROGRAM SECTION (P): 0x000044 
CONSTANT SECTION (C) : 0x000000 
DATA SECTION (D) : 0x000000 
BSS SECTION (B) : 0x000000 


TOTAL PROGRAM SECTION(P): 0x000044 
TOTAL CONSTANT SECTION (P) : 0x000000 
TOTAL DATA SECTION (P) : 0x000000 


TOTALBSS SECTION (P) : 0x000000 


TOTAL PROGRAM 0x000044 


KKK KK KKKKK TARET, INFORMATION RAEKKKKKKKK 


NUMBER OF EXTERNAL REFERENCE SYMBOLS: 
NUMBER OF EXTERNAL DEFINITION SYMBOLS: 


NUMBER OF INTERNAL/EXTERNAL SYMBOLS: 


Figure 1.7 Statistics Information 
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Description: 


(1) Total number of messages by the level 
(2) Number of compiled lines from the source file 
(3) Size of each section and total size of sections 


(4) Number of external reference symbols, number of external definition symbols, and total 
number of internal and external labels 


Note: NUMBER OF INFORMATIONS in messages by the level ((1) above) is not output when 
message option is not specified. Section size information (3) and label information (4) are 
not output if an error-level error or a fatal-level error has occurred or when option 
noobject is specified. In addition, section size information (3) is output (indicated as 
"1") or not output (indicated as "0") according to its specification when option code = 
asmcode is specified. Total area size of each section is not output by Ver. 5.0. 


(5) Command Line Specification 


The file names and options specified on the command line when the compiler is invoked are 
displayed. Figure 1.8 shows an example of command line specification information. 


*** COMMAND PARAMETER *** 


-listfile test.c 


Figure 1.8 Command Line Specification 
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1.3.7 Compiler Environment Variables 


Environment variables to be used by the compiler are listed in table 1.7. 


Table 1.7. Environment Variables 


Environment Variable 
SHC_LIB 


SHC_INC 


SHC_TMP 


SHCPU 


Explanation in Use 


Specifies a directory at which compiler load module and system 
include file exists. To enter commands using the DOS prompt of the 
PC version, specify the directory where the compiler main software 
is installed. This environment variable must be specified. 


Specifies a directory at which a system include file exists. More than 
one directory can be specified by dividing directories using commas. 
A system include file is searched for at a directory specified using an 
include option specified directory, SHC_INC-specified directory, and 
system directory (SHC_LIB) in this order. 


Specifies a directory where the compiler generates a temporary file. 
To enter commands using the DOS prompt of the PC version, this 
environment variable must be specified. For UNIX, a directory 
indicated in TMPDIR is specified when this environment variable is 
specified. If SHC_TMP or TMPDIR is not specified, a temporary file 
is generated in /usr/tmp. 


Specifies CPU type by compiler -cpu option using environment 
variables. The following is specified: 


SHCPU=SH1 (same as -cpu=sh1) 
SHCPU=SH2 (same as -cpu=sh2) 
SHCPU=SHZ2E (same as -cpu=sh2e) 
SHCPU=SHDSP (same as -cpu=sh2) 
SHCPU=SH3 (same as -cpu=sh3) 
SHCPU=SH3E (same as -cpu=sh3e) 
SHCPU=SH4 (same as -cpu=sh4) 


An error will occur if anything other than the above is specified. 
Specifying lower case characters will also generate an error. 


When the specification of CPU by SHCPU environment variable and 
-cpu option differs, a warning message is displayed. -cpu option has 
priority to SHCPU specification. 
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1.3.8 Implicit Declaration by Option 


Using cpu, pic, endian, double, fpu, denormalize, or round option results in an 
implicit #define declaration. See the following. 


Table 1.8 Implicit Declaration 


Option 

cpu = sh1 
cpu = sh2 
cpu = sh2e 
cpu = sh3 
cpu = sh3e 
cpu = sh4 
pic = 1 
endian = big 


endian = little 
double = float 
fpu = single 

fou = double 
denormalize = on 


round = nearest 


Implicit Declaration 
#define _SH1 (including default) 


#define _SH2 
#define _SH2E 
#define _SH3 
#define _SH3E 
#define _SH4 
#define _PIC 
#define _BIG (including default) 
#define _LIT 
#define _FLT 
#define _FPS 
#define _FPD 
#define _DON 
#define _RON 
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The following shows an specification example. 
Example: 


#ifdef BIG 
#ifdef SH1 
asdees os Valid when -cpu=shl1 -endian=big option is specified 
Boe dhe (Also valid when no option is specified for -cpu or -endian) 
#endif 
#endif 
#ifdef SH2 
a4 wd Valid when -cpu=sh2 option is specified 
#endif 
#ifdef SH3 
H#ifdef BIG 
be ile Valid when -cpu=sh3 -endian=big option is specified 
#endif 
#ifdef LIT 
bG@a-isy Valid when -cpu=sh3 -endian=1litt1le option is specified 
#endif 
#endif 
Rules: 1. Ifno option is specified (default), #define _SH1 or #define _BIG is set. 
2. The implicit #define declaration is specified as #undef in the source file. 
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Section 2 C/C++ Programming 


ya | Limits of the Compiler 


Table 2.1 shows the limits on source programs that can be handled by the compiler. Source 
programs must fall within these limits. To edit and compile efficiently, it is recommended to split 
the source program into smaller programs (approximately two ksteps) and compile them 
separately. 


Table 2.1 Limits of the Compiler 


Classification Item Limit 


Invoking the compiler Number of source programs that can be compiled at one time None*' 


Total number of macro names that can be specified using the None 

define option 

Length of file name (characters) 128 
Source programs Length of one line (characters) 32768 

Number of source program lines in one file 65535 

Number of source program lines that can be compiled None 
Preprocessing Nesting levels of files in an #include directive 30 

Total number of macro names that can be specified in a #define None 

directive 

Number of parameters that can be specified using a macro 63 

definition or a macro call operation 

Number of expansions of a macro name 32 

Nesting levels of #if, #ifdef, #ifndef, #else, or #elif directives 32 


Total number of operators and operands that can be specified in 512 
an #if or #elif directive 


Declarations Number of function definitions None 
Number of internal labels*? 32767 
Number of symbol table entries*° 32767 
Total number of pointers, arrays, and functions that qualify the 16 
basic type 
Array dimensions 6 
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Table 2.1 Limits of the Compiler (cont) 


Classification Item Limit 
Statements Nesting levels of compound statements 32 


Nesting levels of statement in a combination of repeat (while, 32 
do, and for) and select (if and switch) statements 


Number of goto labels that can be specified in one function 511 
Number of switch statements 256 
Nesting levels of switch statements 16 
Number of case labels 511 
Nesting levels of for statements 16 
Expressions Number of parameters that can be specified using a function 63*4 


definition or a function call operation 


Total number of operators and operands that can be specified About 500 
in one expression 


Standard library Number of files that can be opened at once in open function 20 


Notes: 1. When entering using the DOS prompt of the PC version, the command line restrictions 
permit inputs of up to 127 characters at one time. 

2. An internal label is internally generated by the compiler to indicate a static variable 
address, case label address, goto label address, or a branch destination address 
generated by if, switch, while, for, and do statements. 

3. The number of symbol table entries is determined by adding the following numbers: 
In case of C compilation: 

Number of external names + number of internal names of each function + number of 
strings + initial value of structure or array in a compound statement + number of 
compound statements + number of case labels + number of goto labels + number of 
typedef names + number of structure/union/enum tags + number of 
structure/union/enum members + number of function prototype declaration parameters 
In case of C++ compilation: 

Number of external names + number of internal names of each function + number of 
strings + initial value of structure or array in a compound statement + number of 
compound statements + number of case labels + number of goto labels + (number of 
default constructors/destructors) + (number of copy constructor/assignment operators) 
+ (number of virtual function tables) + number of class names/enum tags + number of 
class/enum members + number of function prototype declaration parameters 

Items in parentheses are external names the compiler automatically generates at C++ 
compilation. If virtual function tables are to be generated, see section 2.2.2, Internal 
Data Representation. 


4. For nonstatic function members, 62. 
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2.2 Executing a C/C++ Program 


This section covers object programs which are generated by the compiler. The emphasis of the 
explanation is on necessary information to link C/C++ program and assembly program, link C++ 
program and C program, and install program to SuperH microcomputer-applied systems. 


Contents of this section is outlined below. 


2.2.1 Structure of Object Programs: This section discusses the characteristics of memory areas 
used for C/C++ programs and standard library functions. This information is required when 
sections are assigned to memory area. 


2.2.2 Internal Data Representation: This section explains the internal representation of data 
used by a C/C++ program. This information is required when data is shared among C/C++ 
programs, hardware, and assembly programs. 


2.2.3. Linkage with C Programs: This section explains functionality for calling C functions and 
referencing C data from C++ program. 


2.2.4 Linkage with Assembly Programs: This section explains the rules for variables and 
function names that can be mutually referenced by multiple object programs. This section also 
discusses how to use registers, and how to transfer parameters and return values when a C/C++ 
program calls a function. This rule is required for C/C++ program functions calling assembly 
program routines or vice versa. 


This section assumes that the reader has knowledge of SuperH microcomputer hardware. Also 
read the Hardware Manual. 


2.2.1 Structure of Object Programs 


This section discusses the characteristics of memory areas used by a C/C++ program or standard 
library function in terms of the following items. 


1. Section 


Composed of memory areas which are allocated statically by the compiler. Each section has a 
name and type. A section name can be changed by the compiler option sect ion or #pragma 
section. 


2. Write Operation 


Indicates whether write operations are enabled or disabled at program execution. 


3. Initial Value 


Shows whether there is an initial value when program execution starts. 
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4. Alignment 


Restricts addresses to which data is allocated. 


Table 2.2 shows the types of memory area used by C/C++ program and standard libraries, along 
with the outline of their properties. 


Table 2.2 Memory Area Types and Characteristics 


Memory Area Section Section Write Initial 

Name Name*' Type Operation Value Alignment Contents 

Program area P code Disabled Yes 4 bytes*? Stores machine codes. 
(C, C++) 

Constant area C data Disabled Yes 4/8 bytes** — Stores constant data.*° 
(C, C++) 

Initialized data D data Enabled Yes 4/8 bytes** Stores initial value. 

area (C, C++) 

Non-initialized B data Enabled No 4/8 bytes** Stores data whose initial 
data area (C, values are not specified. 
C++) 

Stack area = — — Enabled No 4 bytes Required for program 
(C, C++) execution. Refer to 


section 3.2.2, Dynamic 
Area Allocation. 


Heap area — — Enabled No _— Used by a library 

(C, C++) function (malloc, realloc, 
calloc, and new). Refer 
to section 3.2.2, 
Dynamic Area 


Allocation. 
Address data D_INIT_ data Disabled Yes 4/8 bytes** Stores an address of a 
area of initial constructor to be called 
processing corresponding to a 
(C++) global object. 
Address data D_END_ data Disabled Yes 4/8 bytes** — Stores an address of a 
area of post destructor to be called 
processing corresponding to a 
(C++) global object. 
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Table 2.2 Memory Area Types and Characteristics (cont) 


Memory Area Section Section Write Initial 

Name Name*' Type Operation Value Alignment Contents 

Virtual C_$VTBLdata Disabled Yes 4/8 bytes** Stores data for calling a 

function table virtual function when a 

area (C++) class declaration 
includes the virtual 
function. 


Notes: 1. Section name shown is the default generated by the compiler when a specific name is 
not specified by the compiler -section option. 


2. Becomes 16 bytes when -align1é option is specified. 


3. When compilation observes C++ syntax, initial values including cast and class objects 
including virtual base class or virtual function cannot be assigned to constant area even 
if const is specified. If the initial value is present, these entities are assigned to the 
initialized data area. If the initial value is absent, they are assigned to the non-initialized 
data area. 


4. Ifthe -cpu=sh4 option is specified, alignment is at 8-byte boundaries. 


Example 1: 


This program example shows the relationship between a C program and the areas generated by the 
compiler. 


Prmgmamara mainiig... 
Corctant arma fc} 
lritalized cata area fa) 


Norrinitalizead cata area fo) 


Agpa to be generated by the compiler and 
data to be stoged in it. 
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Example 2: 


This program example shows the relationship between a C++ program and the areas generated by 
the compiler. 


Post processing data arma (&A:: 4h) 


Aga to be generated by the cormpiler and 
data 0 be stowed in it. 
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9 dp 9 Internal Data Representation 


This section explains the internal representation of C/C++ language data types. The internal data 
representation is determined according to the following four items: 


1. Size 


Shows the memory size necessary to store the data. 


2. Alignment 


Restricts the addresses to which data is allocated. There are three types of alignment; 1-byte 
alignment in which data can be allocated to any address, 2-byte alignment in which data is 
allocated to an even byte address, and 4-byte alignment in which data is allocated to an address 
indivisible by four. 


3. Data range 
Shows the range of data of scalar type (C) or basic type (C++). 


4. Data allocation example 


Shows an example of assignment of element data of compound type (C) or class type (C++). 
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(1) Scalar type (C), basic type (C++) 


Table 2.3 shows internal representation of scalar type data in C and basic type data in C++. 


Table 2.3 


Size Alignment 
Data Type (bytes) (bytes) 


char (signed 1 1 
char) 


unsigned char 
short 
unsigned short 
int 

unsigned int 
long 


unsigned long 


p/ A; AL ATL AY] rm] pm] a 


enum 
float 


double grt +? 
long double 


Pe 


& 
HLA] A] ALAR] RY] RI] MTD] A 


Pointer 
Bool** 


Reference*” 


A) AR] aA] A 
HY A] oO] A 


Pointer to a data 
member*” 


Pointer to a 12 4 
function 
member” ** 


Sign 
Used 


Unused 
Used 
Unused 
Used 
Unused 
Used 
Unused 
Used 
Used 
Used 


Unused 
Used 
Unused 
Used 


Internal Representation of Scalar-Type Data 


Data Range 
Minimum Value Maximum Value 
~2" (128) QF 1 (127) 
0 2° — 4 (255) 
-2'° (-32768) 2'° — 1 (32767) 
0 2'° — 1 (65535) 
-2°" (-2147483648) 2°'— 1 (2147483647) 
0 2°* _ 1 (4294967295) 
~2°' (-2147483648) 2°'— 1 (2147483647) 
0 2°* _ 1 (4294967295) 
-2°" (-2147483648) 2° — 1 (2147483647) 
5 too 
—oo too 
0 2°* _ 1 (4294967295) 
2" (128) ey <4 (137) 
0 2°* _ 1 (4294967295) 
0 2° _ 1 (4294967295) 


Notes: 1. The size of double type is 4 bytes if double=float option is specified. 
2: These data types are valid for C++ compilation only, and are not supported in Ver. 5.0. 
3. If cpu=sh4 and fpu=single are both specified, double type and long double type are 
treated as 4 bytes (float type). If cpu=sh4 and fpu=double are both specified, float type 
is treated as 8 bytes (double type). 


4. Pointers to function members are represented by classes in the following. 
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class _PMF{ 


publie: 
size t delta; //Object offset value 
int index; //Index in the virtual function table when 
//the target function is the virtual function 
union { 
int (* deffun) (); //Address of a function when the target 
//function is a non-virtual function 
size_t vt_offset; //Object offset value of the virtual function 
}: //table when the target function is the 
}; //virtual function. 


(2) Compound type (C), class type (C++) 


This section explains internal representation of array type, structure type, and union type data in C 
and class type data in C++. 


Table 2.4 shows internal representation of compound type and class type data. 


Table 2.4 Internal Representation of Compound Type and Class Type Data 


Data Type Alignment (bytes) Size (bytes) Data Allocation Example 
Array Maximum array element Number of array elements x int a[10]; 
alignment element size Alignment: 4 bytes 
Size: 40 bytes 
Structure*' Maximum structure Total size of members*' struct { 
member alignment int a, b; 
} 
Alignment: 4 bytes 
Size: 8 bytes 
Class Maximum alignment of (Sum of member size) + class A { 
pointer to aclass member (Number of pointers to virtual Leck, oa Bye 
(4 bytes), a virtual function function tables) x 4 bytes + Caner 
table**, ora pointer toa | (Number of pointer to virtual virtual void f(); 
virtual base class*°. base class) x 4 bytes bs 
Alignment: 4 bytes 
Size: 12 bytes 
Union Maximum union member Maximum size of member** union { 
alignment int a,b; 


} 
Alignment: 4 bytes 
Size: 4 bytes 
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In the following notes, a rectangle indicates four bytes. The diagonal line represents blank area for 
alignment. 


Notes: 1. When allocating a member of a structure type, an empty area may be created between a 
member and the previous member to adjust the alignment of a data type of the member. 


struct { 
char a; 
int b; }obj; 


When a structure has a four-byte alignment, and the last member ends at the first, 
second or third byte, the remaining bytes are included in a structure type area. 


struct { 
int a; 
char b; }obj; 


2. When a union has a four-byte alignment, and the maximum value of the member size is 
not a multiple of four, the remaining bytes up to a multiple of four are included in the 
union type area. 


union { 


int a; 


char b [7]; }0; 


o.b[0] 
o.b[4] 


o.b[1] 
o.b[5] 


o.b[2] o.b[3] 


o.b[6] | 


3. Examples of assignment of class type data are shown below. 


(a) For class having no virtual base class, base class, or virtual functions 
class A{ 
int datal; 
short data2; 
int data3; 
char data4; 
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public: 

AQ); 

int getDatal() {return data1;} 
}obj; 


eel 
[ebidetee 


(b) For class having virtual functions 
class A{ 


int datal; 
public: 

virtual int getDatal(); 
obj; 


A::getData1 


(c) For class having base class 
class A{ 


char datal; 
char data2; 

}7 

class B:public A{ 
short data3; 

obj; 


A class having the base class is aligned to a four-byte boundary. 
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(d) For class having virtual base class 
class A{ 


short datal; 

he 

class B: virtual protected A{ 
char data2; 


}obj; 


Pointer to virtual base class (generated by compiler) 
obj.data2 


(e) For class having virtual base class, base class, and virtual functions 
class A{ 


short datal; 

virtual short getDatal() ; 
e 
class B:virtual public A{ 


char data2; 


char getData2(); 
short getDatal() ; 
}a 
class C:virtual protected A{ 
int data3; 
ie 
class D:virtual public A,public B,public C{ 
public: 
int data4; 


short getDatal(); 
}obj; 
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Pointer to virtual base class (generated by compiler) 


Pointer to virtual base class (generated by compiler) 


i 
| [esate 


Pointer to virtual base class (generated by compiler) 


obj.data3 
obj.data4 


D::getData1 


(f) For empty class or single class 
class A{ 


void fun() ; 


}obj; 


urny area 


Note: 1. The compiler fills data of 1-byte length to realize that the size of an empty 
class is not 0 (as stipulated in C++ language specifications). 


(g) For class having empty class as base class 
class A{ 


void fun(); 
hs 
class B: A{ 
char b; 


}obj; 


a el 


Note: If nonstatic data members are declared in derived classes, dummy area of the 
base class is not allocated in the object. 
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(h) For class having empty class as derived class 
class A{ 
char a; 
he 
class B:A{ 
}obj; 


ee ae 


Note: If nonstatic data members are declared in the base class, dummy area of 
derived classes is not allocated in the object. 


(i) For empty class having virtual functions 
class A{ 
public: 


virtual int getDatal(); 
sobj; 


Pointer to virtual function table (generated by compiler) 


Virtual function table (generated by compiler) 


A::getData1 


Rev. 1.0, 09/98, page 52 of 476 
HITACHI 


(3) Bit Fields 


A bit field is a member of a structure or a class. This part explains how bit fields are allocated. 
Bit field members: Table 2.5 shows the specifications of bit field members. 


Table 2.5 Bit Field Member Specifications 


Item Specifications 


Type specifier allowed for bit fields (signed) char, unsigned char, char*', bool*! 
(signed) short, unsigned short, enum 
(signed) int, unsigned int 
(signed) long, unsigned long 
How to treat a sign when data is A bit field with no sign (unsigned is specified for type): Zero 
extended to the declared type** extension*® 
A bit field with a sign (unsigned is not specified for type): 
Sign extension** 
Notes: 1. Specification of signed char, unsigned char, char, and bool is permitted only at C++ 
compilation. 
2. To use a member of a bit field, data in the bit field is extended to the declared type. 
One-bit field data with a sign is interpreted as the sign, and can only indicate 0 and —1. 
To indicate 0 and 1, bit field data must be declared with unsigned. 
3. Zero extension: Zeros are written to the high-order bits to extend data. 
4. Sign extension: The most significant bit of a bit field is used as a sign and the sign is 
written to all higher-order bits to extend data. 


Bit field allocation: Bit field members are allocated according to the following five rules: 


1. Bit field members are placed in an area beginning from the left, that is, the most significant bit. 


Example: 
Exarople: 7” ‘ 
struct bit = 
aint a: 2; to: 
int Bb: 3; 
Pi 


2. Consecutive bit field members having type specifier of the same size are placed in the same 
area as much as possible. 


Exarmple: =4 & 
struct bi 2 eel 
Lory Al Bj a. = 
unsigned int bh: 5; 
Py 
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3. Bit field members having type specifier with different sizes are allocated to the following 
areas. 


Example: -3 ‘ 
etemact Bi ae 
int a:5; rr 
a = 
char b: 4; 
¥2; ae 


4. Ifthe number of remaining bits in the area is less than the next bit field size, though type 


specifier indicate the same size, the remaining area is not used and the next bit field is 
allocated to the next area. 


Exarnpe : H 4 4: 
struct b2{ co [ow LT wb Le 
cr : 
char 4:5; = 4 
char b: 4; 
meri 


5. Ifa bit field member with a bit field size of 0 is declared, the next member is allocated to the 


next area. 
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(4) Memory Allocation of Little Endian 
Memory is allocated to a data array using a little endian as follows. 


One-byte data ((signed) char, unsigned char, and bool type): The order of bits in one-byte 
data for a big endian and a little endian is the same. 


Two-byte data ((signed) short and unsigned short type): The upper byte and the lower byte 
will be reversed in two-byte data for a big endian and a little endian. 


Example: When a two-byte data 0x1234 is allocated in an address 0x100: 


big endian: address 0x100: 0x12 little endian: address 0x100: 0x34 
address 0x101: 0x34 address 0x101: 0x12 


Four-byte data ((signed) int, unsigned int, (signed) long, unsigned long, and float type): The 
upper byte and the lower byte will be reversed in four-byte data for a big endian and a little 
endian. 


Example: When an eight-byte data 0x 12345678 is allocated in an address 0x100: 


big endian: address 0x100: 0x12 little endian: address 0x100: 0x78 
address 0x101: 0x34 address 0x101: 0x56 
address 0x102: 0x56 address 0x102: 0x34 
address 0x103: 0x78 address 0x103: 0x12 


Eight-byte data (double type): The order of eight-byte data will be reversed for a big endian and 
a little endian. 


Example: When a four-byte data 0x123456789abcdef is allocated in an address 0x100: 


big endian: address 0x100: 0x01 little endian: address 0x100: Oxef 
address 0x101: 0x23 address 0x101: Oxed 
address 0x102: 0x45 address 0x102: Oxab 
address 0x103: 0x67 address 0x103: 0x89 
address 0x104: 0x89 address 0x104: 0x67 
address 0x105: Oxab address 0x105: 0x45 
address 0x106: Oxcd address 0x106: 0x23 
address 0x107: Oxef address 0x107: 0x01 


Compound-type and class-type data: Members of compound-type and class-type data will be 
allocated in the same way as that of a big endian. However, the order of byte data of each member 
will be reversed according to the rule of data size. 
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Example: When the following function exists in address 0x100: 


struct { 
short a; 
int b; 
}z= {0x1234, 0x56789abc}; 


big endian: address 0x100: 0x12 little endian: address 0x100: 0x34 
address 0x101: 0x34 address 0x101: 0x12 
address 0x102: empty area address 0x102: empty area 
address 0x103: empty area address 0x103: empty area 
address 0x104: 0x56 address 0x104: Oxbe 
address 0x105: 0x78 address 0x105: 0x9a 
address 0x106: 0x9a address 0x106: 0x78 
address 0x107: Oxbe address 0x107: 0x56 


Bit field: Bit fields will be allocated in the same way as a big endian. However, the order of byte 
data in each area will be reversed according to the rule of data size. 


Example: When the following function exists in address 0x100: 


struct { 
long a:16; 
unsigned int b:15; 
short c:5 

}y= {1, 1, 1}; 


big endian: address 0x100: 0x00 little endian: address 0x100: 0x02 
address 0x101: 0x01 address 0x101: 0x00 
address 0x102: 0x00 address 0x102: 0x01 
address 0x103: 0x02 address 0x103: 0x00 
address 0x104: 0x08 address 0x104: 0x00 
address 0x105: 0x00 address 0x105: 0x08 
address 0x106: empty area address 0x106: empty area 
address 0x107: empty area address 0x107: empty area 
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2:2:3 Linkage with C Programs 


The C++ language supports functions such as calling a C function from a C++ program and 
reference to C data. These functions enable you to use C programs and C libraries which have 
already been created. To refer to a C function, use an extern "C" linkage specifier. To refer to a 
global variable, make an extern declaration. An example of calling a C function from a C++ 
program is shown below. 


Example: 
extern "C" int £ (int); //function f is a C program function. 
extern int data; //C program global variable 
void g () 
{ 
a=f (1); //Calling C program function f 
data=2; //Referring to a C program global variable 
} 


2.2.4 Linkage with Assembly Programs 


The compiler supports intrinsic functions such as access to the SuperH microcomputer registers 
as. Refer to section 2.3.2, Intrinsic Functions, for details on intrinsic functions. However, 
processes that cannot be written in C/C++, such as the multiply and accumulate operation using 
the MAC instruction, should be written in assembly language and afterwards linked to the C/C++ 
program. 


This section explains two key items which must be considered when linking a C/C++ program to 
an assembly program: 


External identifier reference 


Function call interface 
(1) External Identifier Reference 


Functions and variable names declared as external identifiers in a C/C++ program can be 
referenced or modified by both assembly programs and C/C++ programs. The following are 
regarded as external identifiers by the compiler: 


A global variable which has a storage class other than static (C/C++ program) 


A variable name declared with storage class extern (C/C++ program) 


Rev. 1.0, 09/98, page 57 of 476 


HITACHI 


A function name whose storage class is other than static (C program) 

Non-member and non-inline function name whose storage class is other than static class 
(C++ program) 

Non-inline member function name (C++ program) 


Static data member name (C++ program) 


When variable names which are defined as external identifiers in C/C++ programs, are used in 
assembly programs, an underscore character (_) must be added at the beginning of the variable 
name (up to 250 characters without the leading underscore). 


Example 1: An external identifier defined in an assembly program is referenced by a C/C++ 
program 


In an assembly program, symbol names beginning with an underscore character (_) are 
declared as external identifiers by an .EXPORT directive. 

In a C/C++ program, symbol names (with no underscore character (_) at the head) are declared 
as external identifiers. 


Assembh progrann (detinition) GAO+ progr (reference) 


_EXPORT _a,. _b autern int a,b: 
. SECTION D,.DATA,ALIGH=4 

.DATA.L 1 

.DATA.L 1 

. EHD 


Example 2: An external identifier defined in a C/C++ program is referenced by an assembly 
program 


In a C/C++ program, symbol names (with no underscore character (_) at the head) are defined 
as external identifiers (global variable) 

In an assembly program, external references to symbol names beginning with an underscore 
character (_) are declared by an IMPORT directive. 
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CiC+ program fdefinitiors Assembly program (reference) 


int a; . IMPORT a 
.SECTIOH F,CODE, ALIGH=2 
Mov.L A_a,R1 
Mov. L @Ri, Ro 
ADD #1, RO 
RTS 
Mov. L RO, @RL 
. ALIGH 4 
A_a: .DATA.L Ja 
. EHD 


(2) Function Call Interface 


When either a C/C++ program or an assembly program calls the other, the assembly programs 
must be created using rules involving the following: 


Stack pointer 
Allocating and deallocating stack frames 
Registers 


RW NHN — 


Setting and referencing parameters and return values 


Stack Pointer: Valid data must not be stored in a stack area with an address lower than the stack 
pointer (in the direction of address H'0), since the data may be destroyed by an interrupt process. 


Allocating and Deallocating Stack Frames: In a function call (right after the JSR or the BSR 
instruction has been executed), the stack pointer indicates the lowest address of the stack used by 


the calling function. Allocating and setting data at addresses greater than this one must be done by 
the calling function. 


After the called function deallocates the area it has set with data, control returns to the calling 
function usually with the RTS instruction. The calling function then deallocates the area having a 
higher address (the return value address and the parameter area). 
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Atter function call and atter 
eontrol etums from «a function 


4 Lower address 


‘Ares allocated by the called function 
tdunng function call) 
Ara deallocated by the called function 
latter control retums from =& funetion) 
:Armadeallocated by the calling function 


{ Upper address 


Figure 2.1 Allocation and Deallocation of a Stack Frame 


Registers: Some registers change after a function call, while some do not. Table 2.6 shows how 
registers change according to the rules. 


Table 2.6 Rules on Changes in Registers After a Function Call 


Item Registers Used in a Function Notes on Programming 

Registers whose RO to R7, FRO to FR11*'**, If registers used in a function contain 

contents may change DRO to DR10*”, FPUL*'*?, and valid data when a program calls the 
FPSCR*'*? function, the program must push the 


data onto the stack or register before 
calling the function. The data in 
registers used in called function can 
be used freely without being saved. 


Registers whose R8 to R15, MACH, MACL, PR, FR12 The data in registers used in 
contents may not to FR15*' **, and DR12 to DR14** functions is pushed onto the stack or 
change register before calling the function, 


and popped from the stack or 
register only after control returns 
from the function. Note that data in 
the MACH and MACL registers are 
not guaranteed if the option 
macsave=0 is specified. 


Notes: 1 Single-precision floating point register for SH2E, SH3E, and SH4 
2 Double-precision floating point register for SH4 
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The following examples show the rules on register changes. 


A subroutine in an assembly program is called by a C/C++ program 


Assembly program (called function) 


. EXPORT sub 


SECTION PF, OoDE, ALTGN=4 

_sub: MOV.L F14,@-R15 Saves the regster usedin te function. 
rev. L FL? ,@-F15 
&D0 #-2,R15 


Processing of he furcion 

(RO to AR? are saved by the calling 
Progr: hey canbe used without 
saving within the called function.) 


Restores the saved registers. 


C/C++ program (calling function) 
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A function in a C/C++ program is called by an assembly program 
C/C++ program (called function) 


Assembly program (calling function) 


IMPORT _sub The called function rane preixed wit (is 
_SECTION F, CODE, ALTGN=4 dedared by the IMPORT directive (0. 

; The extemal rameis declared by the . IMPORT 
directive by the function dada ration 
deinition of the compiler. 

For he generation miles of extemal names, 
see Apoend« G, “Encoding Rules.” 


Store te PR oregster (retum address storage 
ragsten when calling the function. 
fregstrn ROto A? contin valid cata, 

te cata is pushed onto the stack or stored 
IM unused rags ers. 


Calls function sub. 


The PR regsteris restored. 
Address data of function sub. 


Note: The compiler uses a specified rule to convert the external name created by the function 
name or static data member. When you need to know the external name created by the 
compiler, refer to (read) the external name created by the compiler using option 
code=asmor listfile. 


Also see appendix G, Encoding Rules. Defining a C++ function with extern "C" specified 
applies the same generation rules as C functions to external names, although this makes 
overloading of the function impossible. 


Setting and Referencing Parameters and Return Values: This section explains how to set and 
reference parameters and return values. 


This section first explains the general rules concerning parameters and return values, and then how 
the parameter area is allocated, and how areas are established for return values. 
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General rules concerning parameters and return values 

— Passing parameters 
A function is called only after parameters have been copied to a parameter area in registers 
or on the stack. Since the calling function does not reference the parameter area after 


control returns to it, the calling function is not affected even if the called function modifies 
the parameters. 


— Rules on type conversion 


Type conversion may be performed automatically when parameters are passed or a return 
value is returned. The following explains the rules on type conversion. 


e Type conversion of parameters whose types are declared: 


Parameters whose types are declared by prototype declaration are converted to the 
declared types. 


e Type conversion of parameters whose types are not declared: 


Parameters whose types are not declared by prototype declaration are converted 
according to the following rules. 


(signed) char, unsigned char, (signed) short, and unsigned short type parameters are 
converted to (signed) int type parameters. 


float type parameters are converted to double type parameters. 
Types other than the above cannot be converted to another type. 
e Return value type conversion: 


A return value is converted to the data type returned by the function. 


Example: 


(1) lomy ff ); 


long f¢ ) 
{ float x; 
return x; *——— The retum value is converted to long bya 
prototype decleatior 
i 
ka) Wo pp. ¢ Ane, «1s 3: 
a) 
{ char oc; 
Y ¢ 2.0, & 3% 
} $__ vis converted to int because atype is not 
declared for the porarceter. 


1.0 is convertedto int because the type of 
the parsoneter & int 
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Parameter area allocation 

Parameters are allocated to registers, or when this is impossible, to a stack parameter area. 
Figure 2.2 shows the parameter area allocation. Table 2.7 lists rules on general parameter area 
allocation. The this pointer to a nonstatic function member in C++ program is assigned to R4. 


WU Was WI - 
DO se 

Parameter area FRAO (DRAG) 
WM a 


(When CPU is SHEE, SHSE, SH4) 


Figure 2.2. Parameter Area Allocation 
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Table 2.7 


Parameters Allocated to Registers 


Parameter Storage 
Registers 


R4 to R7 


Target Type 


char, unsigned char, bool, short, 
unsigned short, int, unsigned int, 
long, unsigned long, float (when 


General Rules on Parameter Area Allocation 


Parameters Allocated to a Stack 


(1) Parameters whose types are other 
than target types for register passing 


Parameters of a function which has 


2 
CPU is SH1, SH2, SH3), pointer, (2) 


pointer to a data member, and 
reference 


been declared by a prototype 
declaration to have variable-number 


parameters** 
FR4 to FR11 *' For SH2E and SH3E 


e Parameter is float type. 


Other parameters are already 
allocated to R4 to R7. 


Other parameters are already 
allocated to FR4 (DR4) to FR11 
(DR10). 


e Parameter is double type and 
double=float option is 
specified. 

For SH4 


e Parameter type is float type 
and fpu=doub1e option is not 
specified. 

e Parameter type is double type 
and fpu=single option is 
specified. 

For SH4 


e Parameter type is double type 
and fpu=single option is not 
specified. 


DR4 to DR10 ** 


e Parameter type is float type 
and fpu=double option is 
specified. 
Single-precision floating point register for SH2E, SH3E, and SH4 
Double-precision floating point register for SH4 


If a function has been declared to have variable-number parameters by a prototype 
declaration, parameters which do not have a corresponding type in the declaration and 
the immediately preceding parameter are allocated to a stack. 


Notes: 1. 
2. 
3. 


Example: 


int: £2 (int, inte aint « ..)¢ 


£2(a,b,c,x,y,z); < x,y, and zare allocated to a stack. 
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Parameter allocation 
— Allocation to parameter storage registers 


Following the order of their declaration in the source program, parameters are allocated to 
the parameter storage registers starting with the smallest numbered register. Figure 2.3 
shows an example of parameter allocation to registers. 


fichar a,int bj 
{ 


Not quaranteed 


Figure 2.3 Example of Allocation to Parameter Registers 


— Allocation to a stack parameter area 


Parameters are allocated to the stack parameter area starting from lower addresses, in the 
order that they are specified in the source program. 


Note: Regardless of the alignment determined by the structure type, union type, or class type, 
parameters are allocated using 4-byte alignment. Also, the area size for each parameter 
must be a multiple of four bytes. This is because the SuperH microcomputer stack pointer 
is incremented or decremented in 4-byte units. 


Refer to appendix B, Examples of Assigning Arguments, for examples of parameter 
allocation. 


Return value writing area 

The return value is written to either a register or memory depending on its type. Refer to table 
2.8 for the relationship between the return value type and area. 

When a function return value is to be written to memory, the return value is written to the area 
indicated by the return value address. The caller must allocate the return value setting area in 
addition to the parameter area, and must set the address of the former in the return value 
address area before calling the function (see figure 2.4). The return value is not written if its 
type is void. 
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Table 2.8 Return Value Type and Setting Area 


Return Value Type 


(signed) char, unsigned char, 
(signed) short, unsigned short, 
(signed) int, unsigned int, long, 
unsigned long, float, pointer, bool, 
reference, and pointer to a data 
member 


Return Value Area 
RO: 32 bits 


(The contents of the upper three bytes of (signed) char, or 
unsigned char and the contents of the upper two bytes of 
(signed) short or unsigned short are not guaranteed.) 


However, when the -rtnext option is specified, sign 
extension is performed for (signed) char or (signed) short 
type, and zero extension is performed for unsigned char or 
unsigned short type. 


FRO: 32 bits 
(1) For SH2E and SH3E 
e Return value is float type. 
e Return value is double type and double=float 
option is specified. 
(2) For SH4 
e Return value is float type and fpu=doubl1e option is 
not specified. 
e Return value is floating-point type and fpu=single 
option is specified. 


double, long double, structure, union, Return value setting area (memory) 


class, and pointer to a function 
member 


DRO: 64 bits 

For SH4 

e Return value is double type and fpu=single option is 
not specified. 


e Return value is floating-point type and fpu=double 
option is specified. 
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Figure 2.4 Return Value Setting Area Used When Return Value Is Written to Memory 


Zw Extended Specifications 
This section describes compiler extended specifications: 


interrupt functions 

intrinsic functions 

section change function 
single-precision floating-point library 
Japanese description in string literals 
inline function 

inline expansion in assembly language 
specifying two-byte address variable 
specifying GBR base variable 
register save and recovery control 
global variable register allocation 


packed structure 


For some of the extended functions above, data members and function members can be specified. 
Specification format is (class name::member name). For the specifiable member types, see the 
format of each function. 
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2.31 Interrupt Functions 


A preprocessor directive (#pragma) specifies an external (hardware) interrupt function. The 
following section describes how to create an interrupt function. Since the interrupt operation of 
SH3, SH3E, and SH4 differ from that of SH1, SH2, and SH2E, interrupt handlers are necessary. 


(1) Description 


#pragma interrupt (function name [(interrupt specifications) ] 
[, function name [(interrupt specifications)]]) 


Global functions and static function members can be specified for the function name. 
Table 2.9 lists interrupt specifications. 


Table 2.9 Interrupt Specifications 


Item Form Options Specifications 
Stack switching sp= <variable> | |The address of a new stack is specified with a 
specification &<variable> | variable or a constant. 


<constant>  <variable>: Variable value 
&<variable>: Variable (pointer type) address 
<constant>: Constant value 


Trap-instruction return = tn= <constant> Termination is specified by the TRAPA instruction 
specification <constant>: Constant value 
(trap vector number) 


(2) Explanation 


#pragma interrupt declares an interrupt function. An interrupt function will preserve register 
values before and after processing (all registers used by the function are pushed onto and popped 
from the stack when entering and exiting the function). The RTE instruction directs the function 
to return. However, if the trap-instruction return is specified, the TRAPA instruction is executed 
at the end of the function. An interrupt function with no specifications is processed in the usual 
procedure. The stack switching specification and the trap-instruction return specification can be 
specified together. 
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Example: 


#pragma interrupt( f(sp = ptr, tn = 10),A::g) 
extern int STK[100]; 
class A{ 
public: 
static void g(); 
be 


int *ptr = STK. + 100; 
Explanation: 


(a) Stack switching specification: ptr is set as the stack pointer used by interrupt function f. 

(b) Trap-instruction return specification: After the interrupt function has completed its processing, 
TRAPA #H'10 is executed. The SP at the beginning of trap exception processing is shown in 
figure 2.5. After the previous PC (program counter) and SR (status register) are popped from 
the stack by the RTE instruction in the trap routine, control is returned from the interrupt 
function. 

(c) The function member that can be specified in C++ program is the static function member. In 
the example, static function member g of class A is specified as an interrupt function. Note 
that nonstatic function members cannot be specified. 
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Irorreciste hy ate r interrupt Durning inte rupt function Just after the interrupt function 
processing has completed processing 
(rorediate hy beto re the TRAPA 
Lower address instruction i sued) 


Figure 2.5 Stack Processing by an Interrupt Function 


(3) Notes 


Le 


Functions that can be specified for an interrupt function definition are the global function 
(C/C++ program) and static function member (C++ program). A global function is assumed to 
be of the extern storage class even if static is specified. 


The function must return void data. The return statement cannot have a return value. If 
attempted, an error is output. 


Example: 
#pragma interrupt (f1(sp=100) , £2) 
VOU £LO tse ep cwmse daceen dbase emacs (a) 
THe EL0 4 ose p akecexsecene semtet oun iu (b) 


Description: (a) is correct declaration. 
(b) returns type that is not void, thus (b) is incorrect declaration. An error 


is output. 


A function declared as an interrupt function cannot be called within the program. If attempted, 
an error is output. However, if the function is called within a program which does not declare 
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it to be an interrupt function, an error is not output but correct program execution will not be 
guaranteed. 


Example (An interrupt function is declared): 
#pragma interrupt (f1) 
void f£1(void){...} 
Gab fe(){ SiGe] sence neenasavs (a) 


Description: Function fl cannot be called in the program because it is declared as an interrupt 
function. An error is output at (a). 


Example (An interrupt function is not declared): 
Int £4) ¢ 
dGb. £2001 SLAVS) svctsnenavees (b) 


Description: Because function f1 is not declared as an interrupt function, an object for int 
f1(Q); is generated. If function fl is declared as an interrupt function in another 
file, correct program execution cannot be guaranteed. 


2.3.2 Intrinsic Functions 


The compiler provides the intrinsic functions for the SuperH microcomputer, which (functions) 
are described below. 


(1) Intrinsic Functions 
The following functions can be specified by intrinsic functions. 


Setting and referencing the status register 

Setting and referencing the vector base register 

I/O functions using the global base register 

System instructions which do not compete with register sources in C/C++ language 


Multimedia instructions with the use of the floating point unit, setting and referencing control 
registers 


(2) Description 
<machine.h>, <umachine.h>, or <smachine.h> must be specified when using intrinsic functions. 
(3) Intrinsic Function Specifications 


Table 2.10 lists intrinsic functions. 
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Table 2.10 Intrinsic Functions 


No Item Function 
1 Status Setting the status 
register register 

2 jek) Referencing to the 
status register 

3 Setting the interrupt 
mask 

4 Referencing to the 


interrupt mask 


5 Vector base Setting the vector 
register base register 


—— (VBR) 


6 Referencing to the 


vector base register 
7 ~~ Global base Setting GBR 


register 
8 (GBR) Referencing to GBR 
9 Referencing to GBR- 
based byte 
10 Referencing to GBR- 
based word 
11 Referencing to GBR- 


based long word 


Specification 


void set_cr(int cr) 
int get_cr (void) 


void set_imask (int 
mask) 


int get_imask (void) 


void set_vbr (void 
**base) 


void **get_vbr (void) 


void set_gbr (void 
*base) 


void *get_gbr (void) 


unsigned char 
gbr_read_byte (int 
offset) 


unsigned short 
gbr_read_word (int 
offset) 


unsigned long 
gbr_read_long(int 
offset) 
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Description 


Sets cr (32 bits) in the status 
register 


Refers to the status register 


Sets mask (4 bits) in the 
interrupt mask (4 bits) 


Refers to the interrupt mask 
(4 bits) 


Sets **base (32 bits) in 
VBR 


Refers to VBR 
Sets *base (32 bits) in GBR 


Refers to GBR 


Refers to byte data (8 bits) 
at the address indicated by 
adding GBR and the offset 
specified 


Refers to word data (16 bits) 
at the address indicated by 
adding GBR and the offset 
specified 


Refers to long word data 
(32 bits) at the address 
indicated by adding GBR 
and the offset specified 
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Table 2.10 Intrinsic Functions (cont) 


No 
12 


17 


Rev. 


Item Function 

Global base Setting GBR-based 
register byte 

(GBR) 

(cont) 


Setting GBR-based 
word 


Setting GBR-based 
long word 


AND of GBR base 


OR of GBR base 


XOR of GBR base 
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Specification 


void gbr_ write byte 
(int offset, unsigned 
char data) 


void gbr_write_word 


(int offset, unsigned 
short data) 

void gbr_write_long 
(int offset, unsigned 
long data) 

void gbr_and_byte 
(int offset, unsigned 
char mask) 

void gbr_or byte 

(int offset, unsigned 
char mask) 

void gbr_xor byte 


offset, unsigned 
mask) 


(int 
char 
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Description 


Sets data (8 bits) at the 
address indicated by adding 
GBR and the offset 
specified 


Sets data (16 bits) at the 
address indicated by adding 
GBR and the offset 
specified 


Sets data (32 bits) at the 
address indicated by adding 
GBR and the offset 
specified 


ANDs mask with the byte 
data at the address 
indicated by adding GBR 
and the offset specified, and 
then stores the result at the 
same address 


ORs mask with the byte 
data at the address 
indicated by adding GBR 
and the offset specified, and 
then stores the result at the 
same address 


XORs mask with the byte 
data at the address 
indicated by adding GBR 
and the offset specified, and 
then stores the result at the 
same address 


Table 2.10 Intrinsic Functions (cont) 


No Item 


18 Global base TEST of GBR base 


register 
(GBR) 
(cont) 

19 Special 
instruc- 

90 tions 

21 

22 

23 


Function 


SLEEP instruction 


TAS instruction 
TRAPA instruction 
OS system call 


PREF instruction 


Specification 


int gbr_tst_byte 
(int offset, unsigned 
char mask) 


void sleep (void) 


int tas(char *addr) 


Description 


ANDs mask with the byte 
data at the address 
indicated by adding GBR 
and the offset specified, and 
checks if the byte data at 
the offset from GBR is 0 or 
not, and sets the result in 
the T bit 


Expands the SLEEP 
instruction 


Expands TAS.B @addr 


int trapa(int trap no) Expands TRAPA #trap_no 


int trapa_svc 

(int trap_no, int 
code, typel paral, 
type2 para2, type3 
para3, type4 para4) 


trap-no: Trap number 

code: Function code 

para 1 to 4: Parameter (0 to 
4 variables) 
Parameter type 
is general 
integer or 
pointer type 


type 1 to 4: 


void prefetch 
(void *p) 


Note: The instruction is 
prefetched only when the 
compiler option cpu=sh3, 
sh3e, sh4 is specified. 


Enables executing HI7000 
and other OS system calls. 
When trapa_svc is 
executed, code is specified 
in RO, and para 1 to para4 in 
R4 to R7, respectively. 
Then, TRAPA #trap_no is 
executed. 


If the instruction is 
prefetched, an area 
indicated by the pointer 
(16-byte data from (int) 
p&Oxfffffff0) is written to the 
cache memory. This does 
not affect any programming 
logical operation. 
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Table 2.10 Intrinsic Functions (cont) 


No Item Function 

24 Multiply and MAC.W instruction 
accumulate 
operation 

25 MAC.L instruction 

26 Floating Setting FPSCR 
point unit 

27 Referencing FPSCR 
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Specification 


int macw ( 

short *ptrl1, short 
*ptr2, unsigned int 
count ) 


int macwl ( 
short *ptrl1, short 
*ptr2, unsigned int 


count, unsigned int 

mask) 

ptr1: Start address of data 
to be multiplied or 
accumulated 

ptr2: Same as above 

count: Number of times the 
operation is 
performed 

mask: Address mask that 
correspond to the 
ring buffer 

int macl ( 

int *ptr1, int *ptr2, 


unsigned int count) 


int macll ( 

int, *ptrl, ink*ptx2', 
unsigned int count, 
unsigned int mask) 


The parameter specification 
is the same as those of No. 


24. Note: macl and macll can 


be used only when the 
compiler option cpu=sh2, 
sh2e, sh3, or sh3eis 
specified. 


void set_fpscr ( 
Int or 


) 
int get_fpscr() 
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Description 


A multiply and accumulate 
operation intrinsic function 
multiplies and accumulates 
contents of two data tables. 
Example: 


short 
tbl1i[]={al,a2,a3,a4}; 
short 
tbl2[]={b1,b2,b3,b4}; 
In this case, macw(tbl1, tbl2, 
3) calculates a1*b1 
+a2*b2+a3*b3. Using a ring 
buffer function, tblI2 can be 
calculated recursively. The 
number of calculation times 
is 2°. 

Example: When the data 
size is two bytes and the 
ring buffer mask is four 
bytes (Oxfffffffb or up to 
0x4), macwil(tbl1, tbl2, 4, 
Oxfffffffb) is calculated as 
a1*b1+a2*b2+a3*b1 
+a4*b2. 


Sets cr (32 bits) to FPSCR. 


Refers to FPSCR. 


Table 2.10 Intrinsic Functions (cont) 


No 
28 


Item Function 
Single- FIPR instruction 
precision 
floating 
point vector 
operation 

FTRV instruction 


Specification 

float fipr ( 
float vect1[4], 
float vect2 [4] 


float ftrv( 
float veci[4], 
float vec2 [4] 


HITACHI 


Description 


Obtains inner product of two 
vectors. 


Example 


extern float 
data1[4],data2[4]; 


Under conditions above, 
fipr(data1 ,data2) obtains 
inner product of vectors 
data1 and data2. 


Transforms data1 (vector) 
by tbl (4x4 matrix), and 
stores the result to data2 
(vector). Note that tbl need 
be loaded using intrinsic 
function Id_ext(). 


data2 = data’ x tbl 
Example 

extern float tbl[4][4]; 

extern float 
data1[4],data2[4]; 
Id_ext(tbl); 

Under conditions above, 
ftrv(data1 ,data2) transforms 
data1 (vector) by tbl (4x4 


matrix), and stores the result 
to data2 (vector). 


As i= 0, 1, 2, 3; the result in 

data2 will be as follows. 

data2[i]=data1[0]*tbl[O][i] 
+data1[1]*tbl[1][i] 
+data1[2]*tbl[2][i] 
+data1[3]*tbl[3][i] 
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No Item 


30 Single- 
precision 
floating 


operation 


point vector addition of the result 


Table 2.10 Intrinsic Functions (cont) 


Function Specification 


Transformation of 4- void ftrvadd ( 
dimension vector by 


: float vecl1[4], 
4x4 matrix and 


float vec2[4], 


to another 4- 
dimension vector ) 


float vec3 [4] 
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Description 


Transforms data’ (vector) 
by tbl (4x4 matrix), adds the 
result to data2 (vector), then 
stores the sum to data3 
(vector). Note that tbl need 
be loaded using intrinsic 
function Id_ext(). 


data3 = data x tbl + data2 
Example 

extern float tbl[4][4]; 

extern float data1[4]; 
extern float data2[4]; 
extern float data3[4]; 
Id_ext(tbl); 

Under conditions above, 


ftrvadd(data1 ,data2,data3) 
transforms data1 (vector) by 
tbl (4x4 matrix), adds the 
result to data2 (vector), then 
stores the sum to data3 
(vector). 


As i=0, 1, 2, 3; the result in 
data3 will be as follows. 


data3[i]=data1[0]*tbI[0][i] 
+data1[1]*tbl[1][i] 
+data1[2]*tbl[2][i] 
+data1[3]*tbl[3][i] 
+data2[i] 


Table 2.10 Intrinsic Functions (cont) 


No Item Function Specification Description 
31. Single- Transformation of 4- void ftrvsub ( Transforms data1 (vector) 
precision dimension vector by Meee seu fal by tbl (4x4 matrix), subtracts 
floating 4x4 matrix and ‘ data2 (vector) from the 
point vector subtraction of the float vec2[4], result, then stores the 
operation —_ result from another 4- float vec3[4] difference to data3 (vector). 
dimension vector Note that tbl need be loaded 
using intrinsic function 
Id_ext(). 
data3 = data x tbl — data2 
Example 
extern float tbl[4][4]; 


extern float data1[4]; 
extern float data2[4]; 
extern float data3[4]; 
Id_ext(tbl); 

Under conditions above, 


ftrvsub(data1 ,data2,data3) 
transforms data1 (vector) by 
tbl (4x4 matrix), subtracts 
data2 (vector) from the 
result, then stores the 
difference to data3 (vector). 


As i=0, 1, 2, 3; the result in 
data3 will be as follows. 


data3|i]=data1[0]*tbl[O][i] 
+data1[1]}*tbl[1][i] 
+data1[2}*tbl[2][i] 
+data1[3]}*tbl[3][i] 
-data2Ii] 


Rev. 1.0, 09/98, page 79 of 476 


HITACHI 


Table 2.10 Intrinsic Functions (cont) 


No Item Function 


32  Single- Addition of 4- 
precision dimension vectors 
floating 
point vector 
operation 


33 Subtraction of 4- 
dimension vectors 


Specification 

void addé4 ( 
float vec1[4], 
float vec2[4], 
float vec3 [4] 


void subé4 ( 
float vecl1[4], 
float vec2([4], 
float vec3 [4] 


34 Multiplication of 4x4. void mtrx4muli ( 


matrices 
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float mati[4] [4], 
float mat2 [4] [4] 
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Description 


Stores the sum of data‘ 
(vector) and data2 (vector) 
to data3 (vector). 

data3 = data1 + data2 


Example 


extern float data1[4]; 
extern float data2[4]; 
extern float data3[4]; 


Under conditions above, 
add4(data1 ,data2,data3) 
stores the sum of data1 and 
data2 to data3. 


Stores the difference 
between data’ (vector) and 
data2 (vector) to data3 
(vector). 

data3 = data1 - data2 


Example 


extern float data1[4]; 
extern float data2[4]; 
extern float data3[4]; 


Under conditions above, 
sub4(data1 ,data2,data3) 
stores the difference 
between data1 and data2 to 
data3. 


Transforms tbl1 (4x4 matrix) 
by tbl (4x4 matrix), and 
stores the result to tbl2. 
Note that tbl need be loaded 
using intrinsic function 
Id_ext(). 

tbl2 = tbl1 x tbl 


Example 


extern float tbl[4][4]; 
extern float tb!1[4][41; 
extern float tb!2[4][4]; 


Id_ext(tbl); 
Under conditions above, 
mtrx4mul(tbl1 ,tbl2) 


transforms tbl1 by tbl, and 
stores the result to tbl2. 


Table 2.10 Intrinsic Functions (cont) 


No Item Function Specification 

35 Single- Multiplication and void mtrx4muladd ( 
precision addition of 4x4 fieat matifa) [4] 
floating matrices ; 
point vector float mat2[4] [4], 
operation float mat3[4] [4] 

) 
36 Multiplication and void mtrx4mulsub ( 
subtraction of 4x4 


float mat1[4] [4], 
matrices 


float mat2[4] [4], 
float mat3 [4] [4] 


Description 


Transforms tbl1 (4x4 matrix) 
by tbl (4x4 matrix), adds the 
result to tbl2 (4x4 matrix), 
and stores the sum to tbl3 
(4x4 matrix). Note that tbl 
need be loaded using 
intrinsic function Id_ext(). 


tbI3=tbl1*tbl+tbl2 
Example 


extern float tbl[4][4]; 

extern float tbl1[4][4]; 
extern float tbl2[4][4]; 
extern float tbl3[4][4]; 


Id_ext(tbl); 


Under conditions above, 
mtrx4muladd(tbl1 ,tbl2,tb!3) 
multiples tbl1 by tbl (4x4 
matrix), adds the result to 
tbI2 (4x4 matrix), and stores 
the sum to tbl3. 


Transforms tbl1 (4x4 matrix) 
by tbl (4x4 matrix), subtracts 
tbl2 (4x4 matrix) from the 
result, and stores the 
difference to tbl3. Note that 
tbl need be loaded using 
intrinsic function Id_ext(). 


tbI3=tbl1 *tbl-tbl2 
Example 


extern float tbl[4][4]; 

extern float tbl1[4][4]; 
extern float tbI2[4][4]; 
extern float tbl3[4][4]; 


Id_ext(tbl); 


Under conditions above, 
mtrx4mulsub(tbl1 ,tb!2,tbl3) 
multiples tbl1 by tbl (4x4 
matrix), subtracts tbl2 from 
the result, and stores the 
difference to tbl3. 
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Table 2.10 Intrinsic Functions (cont) 


No 
37 


(4) 


Item Function Specification Description 


Access to Load to extension void ld ext ( Loads tbl (4x4 matrix) to 
extension — register extension register. 


; float mat [4] [4] 
register 


Example 
extern float tb![4][4]; 


Under condition above, 
Id_ext(tbl) stores the 
contents of tbl to extension 
register. 


Store from extension void st_ext ( Stores contents of extension 


register float wat {47 [47 register to tbl (4x4 matrix). 


Example 
extern float tbl[4][4]; 


Under condition above, 
st_ext(tbl) stores the 
contents of extension 
register to tbl. 


Notes 


(A) Intrinsic Functions of Global Base Register (GBR) 


le 


The offsets (excluding No. 15 to 18) and masks (excluding No.3) shown in table 2.10, Intrinsic 

Functions, must be constants. 

The specification range for offsets is +255 bytes when the access size is shown as a byte, +510 

bytes when the access size is shown as a word, and +1020 bytes when the access size is shown 

as a long word. 

Masks which can be specified for performing logical operations (AND, OR, XOR, or TEST) 

on a location relative to GBR (global base register) must be within the range of 0 to +255. 

As GBR is a control register whose contents are not preserved by all functions in this compiler, 

take care when changing GBR settings. 

The multiply and accumulate operation intrinsic function does not check for parameters. 

Therefore, keep the following in mind: 

a. Tables indicated by ptrl and ptr2 must be aligned to sizes in 2 bytes and 4 bytes, 
respectively. 

b. Tables indicated by ptr2 in macwl and macwll must be aligned to the size of the ring buffer 
mask x 2. 
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(B) Single-Precision Floating Point Vector Operation and Extension Register Access 
Intrinsic Function are Valid only for SH4. 


When using the vector operation intrinsic function for an interrupt function, note the following. 


(1) Intrinsic functions ld_ext(float[4][4]) and st_ext(float[4][4]) change the floating point register 
bank bit (FR) of the floating point status control register (FPSCR) to access extension register. 
Therefore, when using intrinsic functions Id_ext(float[4][4]) or st_ext(float[4][4]) in an 


interrupt function, change the interrupt mask before and after the vector operation intrinsic 
function. 


Example 
#pragma interrupt (intfunc) 


void intfunc() { 
id_ext(); 


} 


void normfunc() { 


int maskdata=get_imask() ; 
set_imask(15); 

1ld_ext (mat1) ; 
ftrv(vecl,vec2) ; 


set_imask (maskdata) ; 
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(11) Intrinsic functions mtrx4mul, mtrx4muladd, and mtrx4mulsub are 4x4 matrix operations and 
therefore are not commutative. 
Example 
extern float matA[] []; 
extern float matB[] []; 
int judge () { 
float datal[4] [4], data2[4] [4]; 
set_imask(15) ; 
ld_ext (matA) ; 
mtrx4mul (matB,datal);/* datal=matB X matA */ 
ld_ext (matB) ; 
mtrx4mul (matA,data2);/* data2=matA x matB */ 


./*elements of datal[][] and data2[][] do not necessarily match.*/ 


} 
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(5) Example 


#include <machine.h> 
#define CDATA1 0 
#define CDATA2 1 
#define CDATA3 2 
#define SDATA1 4 
#define IDATA1 8 

al 


#define IDATA2 12 


struct { 
char cdatal; /* offset O */ 
char cdata2; /* offset 1 */ 
char cdata3; /* offset 2 */ 
short sdatal; /* offset 4 */ 
int idatal; /* offset 8 */ 
int idata2; /* offset 12 */ 
}table; 
void £(); 
void £() 
{ 
set_gbr( &table); /* Set the start address of x / 
/* table to GBR. */ 
gbr_write_byte( CDATA2, 10); /* Set 10 to table.cdata2. * / 
gbr_write_long( IDATA2, 100); /* Set 100 to table.idata2. * / 
if (gbr_read_byte( CDATA2) != 10) /* Refer to table.cdata2. * / 
gbr_and_byte( CDATA2, 10); /* AND 10 and table.cdata2, * / 
/* and set it in table.cdata2. */ 
gbr_or_byte( CDATA2, Ox0F); /* OR OxXOF and table.cdata2, * / 
/* and set it in table.cdata2. */ 
sleep (); /* Expand to the sleep * / 


/* instruction */ 
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Effective Use of Intrinsic Functions: 


Allocate frequently accessed object to memory and set the start address of the object to GBR. 


2. Instep 1., byte data frequently used in logical operations should be declared within 128 bytes 
of the start address of the structure. As a result, the following instructions can be reduced: start 
address load instruction necessary for structure accessing and load/store instructions necessary 
for performing logical operation. 


(6) Dividing <machine.h> 
<machine.h> is divided as follows to correspond to the SH3, SH3E, SH4 execution mode: 


1. <machine.h>: Overall intrinsic functions 
2. <smachine.h>: Intrinsic functions that can be used in the privilege mode 


3. <umachine.h>: Intrinsic functions except <smachine.h> 


2.3.3 Section Change Function 


A section name to be output in a C/C++ program by the compiler can be changed using #pragma 
section. 


(1) Description 


#pragma section name | value 
<source program> 


#pragma section 
(2) Explanation 


Specify a section name using #pragma section name or #pragma section value. A section after a 
declaration in a source program will be P section name + name (numeric value), D section name + 
name (numeric value), C section name + name (numeric value) and, B section name + name 
(numeric value). A default section name becomes valid after #pragma section is declared. 


(3) Notes 


1. #pragma section must be specified outside the function declaration. 


2. A maximum of 64 section names can be declared in one file. 
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(4) Example 


#pragma section abc 


int a; /* a is allocated to section Babc. */ 

extern const int c=1; /* c is allocated to section Cabc. */ 

£( ) 4 /* £ is allocated to section Pabc. */ 
a=C; 


#pragma section 


int b; /* b is allocated to section B. */ 

g() { /* g is allocated to section P. * / 
lor ene 

} 


In the above example, when the compile option sect ion=P=PROG is specified, f and g are 
allocated to section PROGabe and PROG, respectively. 


2.3.4 Single-Precision Floating-Point Library 


A single-precision floating-point library (mathf.h) can be used in addition to an ANSI standard 
floating-point library (math.h). The single-precision floating-point library consists of functions 
listed in table 2.11. 


(1) Description 


A suffix fis added to a double-precision ANSI standard library function name to be a single- 
precision floating point library function name. If a parameter or return type is double or pointer to 


a double-type, it will be float or pointer to float, respectively. Other specifications are the same as 
those of the ANSI standard C library. 


(2) Notes 


Before using this library, be sure to declare #include<mathf.h> and #include<math.h>. 
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Table 2.11 Function List of Single-Precision Floating-Point Library 


Function Name 

float acosf (float x) 

float asinf (float x) 

float atanf (float x) 

float atan2f (float y, float x) 
float cosf (float x) 

float sinf (float x) 

float tanf (float x) 

float coshf (float x) 

float sinhf (float x) 

float tanhf (float x) 

float expf (float x) 

float frexpf (float x, int *p) 


float Idexpf (float x, int i) 
float logf (float x) 

float log1Of (float x) 

float modff (float x, float *p) 


float powf (float x, float y) 
float sqrtf (float x) 

float ceilf (float x) 

float fabsf (float x) 

float floorf (float x) 

float fmodf (float x, float y) 
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Description 

Anti cosine: acos x 

Anti sine: asin x 

Anti tangent: atan x 

Anti tangent of a result given by division: atan (x / y) 
Cosine: cos x 

Sine: sin x 

Tangent: tan x 

Hyperbolic cosine: cosh x 
Hyperbolic sine: sinh x 
Hyperbolic tangent: tanh x 
Exponential function: e* 


Divided into [0.5,1.0), and the square of two and multiplication: 
suppose result=frexp (x, p), x=2*p x result (0.5 = result < 1.0) 


Square of two and multiplication: x X 2 
Natural logarithm: log x 
Common logarithm that has 10 as a base: logiox 


Suppose result = modff (x, y),x is divided into integer *p and 
floating point result 


Square: x” 
Positive square root: ¥* 
Result given by rounding up numbers after a decimal point of x 


Absolute value: | x | 


Result given by rounding down numbers after a decimal point of x 


Remainder after division 
Suppose result = fmodf (x, y) and q quotient, x = q x y + result 
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2.35 Japanese Description in String Literals 


Japanese can be included in string literals. Select a character code of euc or sjis option. When 
this option is omitted, the default setting is specified as table 2.12. 


Table 2.12 Default Settings of Japanese Code 


Host Computer Default Settings 
SPARC EUC 

HP9000 / 7000 Shift JIS 

PC Shift JIS 


Note: The character code in the object program will be the same as that in the source program. 
Character constants cannot be specified in Japanese. 


2.3.6 Inline Function 
A function name to expand at compilation is specified. 
(1) Description 
#pragma inline (function name, ...) 
Global functions and function members can be specified for the function name. 
(2) Explanation 


A function specified by #pragma inline or a function with specifier inline (C++) will be expanded 
where the function is called. However, a function will not be expanded where the function is 
called in the following cases: 


e a function definition exists before the #pragma inline specification 
e a function has a flexible parameter 
© aparameter address is referenced in a function 


e an address of a function to be expanded is used to call a function 
(3) Notes 


1. Specify #pragma inline before defining a function. 


2. When program file includes an inline function description, be sure to specify static before the 
function declaration because an external definition is generated for a function specified by 
#pragma inline. If static is specified, an external definition will not be created. External 
definition will not be created for functions for which inline (C++) is specified. 
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(4) Example 


Source Program Inline expansion Image 
#pragma inline (func) LHe SX; 
static int fune (int a, int b) main( ) 
{ { 
return (a+b) /2; int func_result; 

} { 
amt int a_l= 10, b_1 = 20; 
main( ) fune_result = (a_1+b _1)/2; 
{ } 

x = £fune(10, 20); x = func result; 
} } 


23.7 Inline Expansion in Assembly Language 


A function that is written in an assembly language is expanded where the function is called in a 
C/C++ source file. 


(1) Description 
#pragma inline_asm (function name[(size=numeric value)], ...) 


Only global functions can be specified for the function name. Function members cannot be 
specified. 


(2) Explanation 


Parameters of a function that is written in an assembly language are referenced from an inline_asm 
function because they are stacked or stored in registers in the same way as general function calls. 
Return values of an inline function written in an assembly language should be set in RO. When the 
cpu is SH2E, SH3E, or SH4, return values of single-precision floating point type should be set in 
FRO. When the cpu is SH4, return values of double-precision floating point type should be set in 
DRO. Different registers should be used depending on combination with options. For details, see 
table 2.8, Return Value Type and Setting Area, in section 2.2.4 (2), Function Call Interface. 


Length of an inline function written in an assembly language can be specified by (size=numeric 
value). 
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(3) Notes 


1. Specify #pragma inline_asm before defining a function. 


2. When a source program file includes an inline function description, be sure to specify static 
before the function declaration because an external definition is generated for a function 
specified by #pragma inline_asm. If static is specified, an external definition will not be 
created. 

3. Be sure to use local labels in a function written in an assembly language. 


4. When using registers R8 to R15 in a function written in an assembly language, the contents of 
these registers must be saved and recovered at the start and end of the function. Also, when 
using registers FR12 to FR15 (with the SH2E, SH3E, or SH4 cpu), or when using registers 
DR12 to DR14 (with the SH4 cpu), the contents of these registers must be saved and recovered 
at the start and end of the inline function written in an assembly language. 

5. Do not use RTS at the end of a function written in an assembly language. 


6. When using this function, be sure to compile programs using the object type specification 
option code=asmcode. 

7. When specifying a number by (size=numeric value), specify a number larger than the actual 
object size. Ifa value smaller than the actual object size is specified, correct operation will not 
be guaranteed. Ifa floating point or a numeric value below 0 is specified, an error will occur. 

8. When using registers specified by the #pragma global_register function, the contents of the 
registers must be saved and recovered at the start and end of the inline function written in an 
assembly language. 

9. Only global functions can be specified for the function name. Function members can be 
specified. 


10. Do not use a statement that generates a literal. 
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(4) Example 


Source Program Output Result (partial) 

#pragma inline asm(rot1) 
static int rotl (int a) _main ;function main 
{ ;frame size = 4 

ROTL R4 MOV .L R14, @-R15 

MOV R4, RO MOV.L L220+2, R14; x 
} MOV .L b220+6, R3 ; H'5S5555555 
int x; MOV.L R3, @R14 
main( ) MOV R3, R4 
{ BRA L219 

x = 055555555; NOP 

x = rotl(x); L220: 
} .RES.W 1 

-DATA.L x 


-DATA.L H’'55555555 


L219 
ROTL R4 
MOV R4, RO 
- ALIGN 4 
MOV .L RO, @R14 
RTS 
MOV.L @R15+, R14 
-SECTION B, DATA, ALIGN=4 
_: sstatie: x 
-RES.L 1 
END 
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2.3.8 Specifying Two-byte Address Variables 


A variable can be allocated to a two-byte address area (H'0000000 to H'0007FFF and H'FFF8000 
to H'FFFFFFF). 


(1) Description 
#pragma abs 16 (identifier, ...) 


For the identifier, variables, global functions, static data members, and function members can be 
specified. 


(2) Explanation 


A variable specified using an identifier or an address of a function is treated as two-byte data. 
Then, program size can be reduced. 


(3) Notes 


1. Directive #pragma abs16 cannot be used to specify an automatic object or non-static data 
member. 


2. Variables declared in directive #pragma abs16 must be allocated in addresses H'0000000 to 
H'0007FFF or H'FFF8000 to H'FFFFFFF. 


2.3.9 Specifying GBR Base Variables 
A variable is accessed using a GBR register with an offset value. 
(1) Description 


#pragma gbr_base (variable name[= section name]....) 
#pragma gbr_basel (variable name[= section name].,...) 


For the variable name, variables and static data members can be specified. 
For the section name, names or values can be specified. 
(2) Explanation 


If no section name is specified, the variable specified by #pragma gbr_base is assigned to section 
$G0, and the variable specified by #pragma gbr_basel is assigned to section $G1. Ifa section 
name is specified, the variable specified by #pragma gbr_base is assigned to "$G0 section name + 
name (numeric value)," and the variable specified by #pragma gbr_basel is assigned to "$G1 
section name + name (numeric value)." 
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The directive #pragma gbr_base is used when the variable is located in an offset of 0 to 127 bytes 
from the address specified by the GBR register. The directive #pragma gbr_basel is used when 
the variable is located in an offset of 128 or more bytes from the address specified in the GBR 
register, that is, when a variable is in a range that cannot be accessed by #pragma gbr_base. An 
offset value is 255 bytes at maximum for a char or unsigned char type, 510 bytes at maximum for 
a short or unsigned short, and 1020 bytes at maximum for an int, unsigned, long, unsigned long, 
float, or double type. Based on the above specification, the compiler generates an object program 
in a GBR relative addressing mode that is optimized according to variable reference and settings. 
The compiler also generates an optimized bit instruction in the GBR indirect addressing to char or 
unsigned type data in the $G0 section. 


(3) Notes 


1. Ifthe total program size after linking with section $G0 exceeds 128 bytes, the correct operation 
will not be guaranteed. In addition, if there is data that has an offset value that exceeds those 
specified above for #pragma gbr_basel in section $G1, correct operation will not be 
guaranteed. 


2. Section $G1 must be allocated immediately after 128 bytes of section $GO when linking. 


3. When using this function, be sure to set the start address of section $GO in the GBR register at 
the beginning of program execution. 


4. Static data members can be specified, but non-static data members cannot be specified. 
5. Section name specification is not supported by the Ver. 5.0 of the compiler. 
2.3.10 Register Save and Recovery Control 


Register contents of a function can be saved or recovered. 


(1) Description 


#pragma noregsave (function name, ...) vet ‘Seve ©! ©\4 
#pragma noregalloc (function name, ...) ..cf exc * 4 
#pragma regsave (function name, ...) save /2ecey 


Global functions and function members can be specified for the function name. 
(2) Explanation 


1. Functions specified by #pragma noregsave do not save or allow the recovery of the contents of 
registers to guarantee their values (see table 2.6) at the beginning or end of a function. 


2. Functions specified by #pragma noregalloc do not save or allow the recovery of the contents of 


registers to guarantee their values at the beginning or end of a function, but do generate an 
object before or after the function call. Registers R8 to R14 are not allocated to the object. 


Rev. 1.0, 09/98, page 94 of 476 
HITACHI 


3. Functions specified by #pragma regsave save or allow the recovery of the contents of registers 
to guarantee their values at the beginning or end of a function, but do generate an object before 
or after the function call. Registers R8 to R14 are not allocated to the object. 


4. #pragma regsave and #pragma noregalloc can specify the same function at the same time. In 
this case, the contents of registers R8 to R14 that guarantee their values are saved and 
recovered at the beginning or end of a function, and generate an object before or after the 
function call. Registers R8 to R14 are not allocated to the object. 


5 Functions specified by #pragma noregsave can be used in the following conditions: 
a. A function is first activated and is not called from any other function. 
b. A function is called from a function that is specified by #pragma regsave. 


c. A function is called from a function that is specified by #pragma regsave via #pragma 
noregalloc. 


(3) Notes 


If a function that is specified by #pragma noregsave is called in a way other than explained above, 
the obtained data is not guaranteed. 


(4) Example 


#pragma noregsave (f, A::j) 
#pragma noregalloc (g) 
#pragma regsave (h) 
class A{ 

public: 

void j(); 

Si 

void £(); 

void g(); 

void h(); 

void h() 


{ 


f ( ); /* function call immediately after function call (f) */ 
/* #pragma noregsave * / 


} /* from function (h) #pragma regsave */ 


void g ( ) 


£ (); /* function call (f, A::j) #pragma noregsave from */ 
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/* function (h) #pragma regsave via function (g) */ 


/*#pragma nore galloc x / 
A::3(); 
} 
void £ ( ) 
{ 
} 


2.3.11 Global Variable Register Allocation 

This function assigns a global variable or a static data member to a register. 

(1) Description 

#pragma global_register (<variable name>=<register name>, ...) 

Global variables and static data members can be specified for the variable name. 
(2) Explanation 


This function allocates the register specified in <register name> to the variable specified in 
<variable name>. 


(3) Notes 


1. This function is used for a simple or pointer type variable in the global variable. Do not 
specify a double type variable unless double=float option is specified (except for using 
SH4). 


2. Only use registers R8 to R14, FR12 to FR15 (FR12 to FR15: when using SH2E, SH3E, or 
SH4) and DR12 to DR14 (when using SH4). 
3. The initial value cannot be set. In addition, the address cannot be referenced. 
4. The specified variable cannot be referenced from the linked side. 
5. Static data members can be specified. Nonstatic data members cannot be specified. 
— Type of variables that can be set in FR12 to FR15 
For SH2E and SH3E 
float type variables 
double type variables (when double=float option is specified) 
For SH4 
float type variables (when fpu=doub1e option is not specified) 


double type variables (when fpu=single option is specified) 
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— Type of variables that can be set in DR12 to DR1I5 
For SH4 


float type variables (when fpu=doubl1e option is specified) 
double type variables (when fpu=sing1le option is not specified) 


(4) Example 


#pragma global register (a=R8,A::b=R9) 
class A{ 
public: 


static int b; 


2.3.12 Alignment of Structure/Class Members 
This function aligns structure type, union type, and class type members to 1-byte boundaries. 
(1) Description 


#pragma pack1l 


#pragma unpack 
(2) Explanation 


This function aligns structure type, union type, and class type members that are declared after 
#pragma pack! is specified to 1-byte boundaries. 


This function aligns structure type, union type, and class type that are declared after #pragma 
unpack is specified to maximum boundaries of member. 
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(3) Example 


#pragma packl 

struct A { /* 1-byte boundary */ 
int a; 
char b; 

he 

#pragma unpack 

struct B { /* 4-byte boundary */ 
short a; 
int b; 
char @c; 


‘3 


Note: This extension function is not supported by Ver. 5.0. 


2.4 Notes on Programming 


This section contains notes on coding programs for the compiler and troubleshooting when 
compiling or debugging programs. 


2.4.1 Coding Notes 
(1) float Type Parameter Function 


Functions must declare prototypes or treat float type as double type when receiving and passing 
float type parameters. Data cannot be preserved (guaranteed) when a float type parameter 
function without a prototype declaration receives and passes data. 
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Example: 


void £ (float) ; 


void g () 
{ 
float a; 
£ (a); 
} 
void £ (float x) 
{ 
} 


Function f has a float type parameter. Therefore, a prototype must be declared. 
(2) Program Including an Expression with Two or More Side Effects 


The effect of the execution is not guaranteed in a program whose execution results differ 
depending on the evaluation order. 


Example: 
ali]=a[++il; The value of i on the left side differs depending on whether the 
right side of the assignment expression is evaluated first. 
sub(++i, i); The value of i for the second parameter differs depending on 


whether the first function parameter is evaluated first. 
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(3) Overflow Operation and Zero Division 


At run time if overflow operation or zero division is performed, error messages will not be output. 
However, if an overflow operation or zero division is included in the operations for one or more 
constants, error messages will be output at compilation. 


Example: 
void main() 
int ia; 
int ib; 
float fa; 
Float fb; 
ib=32767; 
fb=3 .4e+38f; 
/* Compilation error messages are output when an overflow */ 
/* operation and zero division are included in operations */ 
/* for one or more constants. */ 
1a=99999999999; /* (W) Detect integer constant overflow. */ 
fa=3.5e+40f; /* (W) Detect floating pointing constant */ 
/* overflow. */ 
ia=1/0; /* (E) Detect division by zero. */ 
fa=1.0/0.0; /* (W) Detect division by floating point */ 
/* zero. */ 
/* No error message on overflow at execution is output. */ 
ib=ib+32767; /* Ignore integer constant overflow. */ 
fb=fb+3.4e+38f; /* Ignore floating point constant */ 
/* overflow. * / 
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(4) Code that may be Deleted at Optimization 


If a program includes consecutive references to the same variable or an expression of which result 
is not used, they may be deleted as redundant code at optimization by the compiler. To keep them 
in the program, specify volatile at declaration. 


Example 1: 
b = a; /* The first expression may be deleted * / 
b = a; /* as redundant code * / 
Example 2: 
while(1) a; /* References to variable a and this loop statement */ 


/* may be deleted as redundant code */ 


(5) Assignment to const Variables 


Even if a variable is declared with const type, if assignment is done to a variable other than const 
converted from const type or if a program compiled separately uses a parameter of a different 
type, the compiler cannot detect the error. 


Example: 
const char *p; /* Because the first parameter p in library */ 
/* function strcat is a pointer for char, * / 
/* the area indicated by the parameter p */ 
strceat(p, "abc") /* may change. * / 
file 1 
const int i; 
Fide 2 
extern int i; /* In file 2, parameter i is not declared as*/ 
/* const, therefore assignment to it in */ 
i=10; /* file 2 is not an error * / 
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(6) Precision of Mathematical Function Libraries 


For function acos (x) and asin (x), an error is large around x=1. Therefore, precautions must be 
taken. Note the error range below. 


Absolute error for acos (1.0 — €) double precision ao? (g= ae 
single precision 2~' (e = 27'’) 


Absolute error for asin (1.0 — €) double precision 2 (e= oo 
single precision 2~' (e = 27'°) 
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2.4.2 Notes on Program Development 
Table 2.13 shows troubleshooting for developing programs from compilation through debugging. 


Table 2.13 Troubleshooting 


Trouble Check Points Solution References 
When linking, error The section name which is output Specify the Section 2.2.1, Structure 
314, cannot found by the compiler must be specified correct section of Object Programs 
section, is output in capitals in start option of name. 
linkage editor. 
When linking, error _ If identifiers are mutually Refer to Section 2.2.4 (1), 
105, undefined referenced by a C/C++ program parameters with External Identifier 
external symbol, is | and an assembly program, an the correct Reference 
output underscore must be attached to parameters. 
the symbol in the assembly 
program. 
Check if the C/C++ program uses_ Specify a Standard library 
a library function. standard library specification: Section 
as the input 1.3.5, Correspondence 
library at to Standard Libraries 
linkage. 
An undefined reference symbol Routine: Section 
identifier must not start with a _ 3.2.1(2), Static Area 
_(A run time routine in a standard Size Calculation 
library must be used.) 
Check if a standard I/O library Create low level Section 3.4.6, Creating 
function is used in the program. interface Low-Level Interface 
routines for Routines 
linking. 
Debugging at the Check if debug option at Specify debug Section 1.3.3, Compiler 
C/C++ source level compilation and sdebug option at option at Options 
cannot be performed linking are specified. compilation and 
sdebug option 
at linking. 
A linkage editor of Ver. 6.0 or Use a linkage 
higher must be used. editor of. Ver. 
6.0 or higher. 
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Table 2.13 Troubleshooting (cont) 


Trouble Check Points 


When linking, error Check if an offset value of a 
No. 108, relocation variable specified using a GBR 
size overflow, is base is within the range. 


output 


When linking, error Check if a variable or function 


No. 104, duplicate whose name is the same as that of 


symbol, is output other variables or functions exists 
in more than one file. 


Check if a variable or function is 
externally defined in a header file 
to be included in more than one 
file (the above is the same in the 
case of a function specified 
(#pragma inline/ inline_asm). 
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Solution References 


Delete #pragma Section 2.3.9, 
gbr_base/gbr_b Specifying GBR Base 
ase1 Variables 

declaration for 

data beyond 

the range. 


Change the 
name of the 
variable or 
function, or 
specify static. 


Specify static. | Section 2.3.6 (3), 
Notes, and 2.3.7 (3), 
Notes 


Section 3 System Installation 


3.1 Overview of System Installation 


The following sections explain how to install a C/C++ program to a system that uses the SuperH 
microcomputer. 


Before installing a C/C++ program to the system, preparations below are necessary. 


(1) Memory assignment 


Each section, stack area, and heap area of the C/C++ program must be assigned to memory 
area of ROM and RAM on the system. 


(2) Preparation of C/C++ program execution environment 


Preparation of C/C++ program execution environment consists of register initialization, 
memory area initialization, and C/C++ program initiation. These functions must be 
implemented by an assembly program. 


If I/O or other library functions are to be used, the libraries must be initialized for preparation of 
execution environment. 


Section 3.2 explains the concept of address assignment of C/C++ program to memory area, and 
describes how to specify linkage editor commands to determine addresses, using examples. 


Section 3.3 explains execution environment preparations, and describes examples of preparation 
programs. 


Section 3.4 explains initialization of library functions and creation of low-level routines. 


Note: If I/O function (stdio.h) and memory allocation function (stdlib.h) are used, the user must 
create low-level I/O routines and memory allocation routines appropriate to the user 
system. 
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3.2 Allocating Memory Areas 


To install an object program generated by the compiler on a system, determine the size of each 
memory area, and allocate the areas appropriately to the memory addresses. 


Some memory areas, such as the area used to store machine code and the area used to store data 
declared using external definitions or static data members, are allocated statically. Other memory 
areas, such as the stack area, are allocated dynamically. 


This section describes how the size of each area is determined and how to allocate an area in 
memory. 


3.2.1 Static Area Allocation 
(1) Data to be Allocated in Static Area 


Individual sections of object program (program area, constant area, initialized data area, non- 
initialized data area, address data area of initial processing, address data area of post processing, 
and virtual function table area) are assigned to static area. 


(2) Static Area Size Calculation 


Calculate the static area size by adding the size of compiler-generated object program and that of 
library functions used by the C/C++ program. After object program linkage, determine the static 
area size from each section size including library size output on a linkage map listing. Before 
object program linkage, the approximate size of the static area can be determined from the section 
size information on a compile listing. Figure 3.1 shows an example of section size information. 
Total area size of each section is not output by Ver. 5.0. 


kok ke & #& * SECTION SIZE INFORMATION * * * * * * * 


PROGRAM SECTION (P) :0x00004A Byte(s) 
CONSTANT SECTION (C) :0x000018 Byte(s) 
DATA SECTION (D) :0x000004 Byte(s) 
BSS SECTION (B) :0x000004 Byte(s) 


TOTAL PROGRAM SECTION :0x00004A Byte 
TOTAL CONSTANT SECTION :0x000018 Byte 
TOTAL DATA SECTION :0x000004 Byte 
TOTAL BSS SECTION :0x000004 Byte 


TOTAL PROGRAM SIZE :0x00006A Byte(s) 


Figure 3.1 Section Size Information 
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If the standard library is not used, calculate the static area size by adding the memory area size 
used by sections shown in section size information. However, if the standard library is used, add 
the memory area used by the library functions to the memory area size of each section. The 
standard library includes C library functions based on the C language specifications and arithmetic 
routines (run time routines) required for C/C++ program execution. Accordingly, link the 
standard library to the C/C++ source program even if library functions are not used in the C/C++ 
source program. 


The compiler provides the standard library including library functions (based on the C/C++ 
language specifications), and arithmetic routines (runtime routines required for C/C++ program 
execution). The size required for run time routines must also be added to the memory area size in 
the same way as library functions. 


The run time routine used by the C/C++ programs are output as external reference symbols in the 
assembly programs generated by the compiler (option code=asmcode). The user can see the 
run time routine names used in the C/C++ programs through the external reference symbols. The 
execution routine name can also be checked by the use of the list file option. 


The following shows the example of C/C++ program and assembly program listings. 


C/C++ program 


int @, int b) 


a /=b; 


return a; 
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Assembly program output by the compiler 


. IMPORT _ _divis ;An external reference definition 


;for the run time routine 
. EXPORT _f 
. SECTION P, CODE, ALIGN=4 
;function: f£f 
;frame size=4 
jused runtime library name: 
;  divis 
PR, @-R15 
RS, RO 
L218, R3 ;_ _divls 
@R3 
R4, R1 
@R15+, PR 


Assembly program output by the C++ compiler 


. IMPORT _ _divls j;An external reference definition 
;for the run time routine 

. EXPORT _ _£ Feira 

. SECTION P, CODE, ALIGN=4 

_f _FSiTas ;function: £ (signed int, signed int) 
;frame size=4 
jused runtime library name: 
;_ _divls 
PR, @-R15 


R5, RO 

L218, R3 ;_ _divls 
@R3 

R4, R1 

@R15+, PR 


In the above example, _ _divls is a run time routine used in the C/C++ program. 
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(3) ROM and RAM Allocation 


When allocating a program to memory, allocate static areas to either ROM and RAM as shown 
below. 


Program area (section P): ROM 

Constant area (section C): ROM 

Non-initialized data area (section B): RAM 

Initialized data area (section D): ROM and RAM (for details, refer to the following section) 
Address data area of initial processing *' (Section D_INIT_): ROM 

Address data area of post processing *' (Section D_END_): ROM 

Virtual function table area ** (Section C_SVTBL): ROM 


Notes: 1. Created by the compiler if a global class object is found during C++ compilation. 


2. Created by the compiler if a virtual function declaration is found during C++ 
compilation. 


(4) Initialized Data Area Allocation 


The initialized data area contains data with initial value. Since the C/C++ language specifications 
allow the user to modify initialized data in programs, the initialized data area must be allocated to 
ROM when linking and is copied to RAM before program execution. Therefore, the initialized 
data area must be allocated in both ROM and RAM. 


However, if the initialized data area contains only static variables that are not modified during 
program execution, the initialized data needs to be allocated only to the ROM area. In this case, 
the data does not need to be allocated to the RAM area. 


(5) Memory Area Allocation Example and Address Specification at Program Linkage 


Each program section must be addressed by the option or subcommand of the linkage editor when 
the absolute load module is created, as described below. 


Figure 3.2 shows an example of allocating static areas. 


Rev. 1.0, 09/98, page 109 of 476 
HITACHI 


Program area 
(0) 

area (D_ MIT 

wea (D_BYD_) 


Virtual tuncton 
toble area (C_ $v TEL 


hitalized dat area 
= _HIT_ 

Norrinifakzed D-END_, 
ops C_S$VTBL: Defiultsection rame 

dee generted by the 
Pi 
con piler 

O»FFFR200 


Ox FFFFFFF Ri: Secion name spected 
by the linkage editor 
Rotel support function 


Figure 3.2 Static Area Allocation 


Specify the following subcommands when allocating the static area as shown in figure 3.2. 


MOAT i i iin tc tsk (1) 
STARTAP,C,D,D_INT_,D_END_,C_$VTBL(400) ,R,B(9000000) ----------- (2) 
Description: 


(1) Define section R having the same size as section D, in the output load module. To reference 
the symbol allocated to section D, reallocate to the address of section R and reference to the 
symbol in section R. Sections D and R are allocated to initialized data section in ROM and 
RAM, respectively. 

(2) Allocate sections P, C, D, D.IINT_, DLEND_, C_$VTBL to internal ROM starting from 
address 0x400 and allocate sections R and B to RAM starting from address 0x9000000. 
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3.2.2 Dynamic Area Allocation 
(1) Dynamic Areas 
Two types of dynamic areas for C/C++ program are used: 


1. Stack area 


2. Heap area (used by the memory allocation library functions) 
(2) Dynamic Area Size Calculation 


Stack Area: The stack area used in C/C++ programs is allocated each time a function is called 
and is deallocated each time a function is returned. The total stack area size is calculated based on 
the stack size used by each function and the nesting of function calls. 


Stack Area Used by Each Function: The object list (frame size) output by the compiler 
determines the stack size used by each function. The following example shows the object list, 
stack allocation, and stack size calculation method. 


Example: The following shows the object list and stack size calculation in a C program. 
The same calculation method is also applicable to C++ program. 


extern int h(char, int *, double); 


int h(char a, register int *b, double c) 


{ 
char *d; 
d= &a; 
h(*d,b,c) ; 
{ 
register int i; 
i= *d; 
return i; 
} 
} 
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KKKKAKKKKEKKEK OBJECT LISTING *#*** kk KKKKK 


FILE NAME: m0251.c 


SCr OFFSET CODE C LABEL INSTRUCTION OPERAND COMMENT 
P 
00000000 h: ; function: h 


; frame size=20 


00000000 2FE6 MOV.L R14,@-R15 
00000002 4F22 STES..L: PR,@-R15 
Liwarer 
address 
RAIXSP) ae 0 


20 


Upper t Stack 
address 


The size of the stack area used by a function is equal to frame size. Therefore, in the above 


example, the stack size used by the function h is 20 bytes which is shown as frame size = 20 in 
COMMENT in OBJECT LISTING. 


For details on the size of parameters to be pushed onto the stack, refer to the description of 
parameter and return value setting and referencing in section 2.2.4 (2), Function Call Interface. 
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Stack size calculation: The following example shows a stack size calculation depending on the 
function call nesting. 


Example: Figure 3.3 illustrates the function call nestings and stack size. 


Function Mame Stack Size (Bytes) 


ot 


32 
24 


Figure 3.3 Nested Function Calls and Stack Size 


If function g is called via function f, the stack area size is calculated according to the formula 
listed in table 3.1. 


Table 3.1 Stack Size Calculation Example 


Call Route Sum of Stack Size (Bytes) 
main (24) > f (32) > g (24) 80 
main (24) > g (24) 48 


As can be seen from table 3.1, the maximum size of stack area required for the longest function 
calling route should be determined (80 bytes in this example) and this size of memory should be 
allocated in RAM. 


When using standard library functions, the stack area sizes for library functions must also be 
accounted for. Refer to the Standard Library Memory Stack Size Listing, included with the 
compiler package. 


Note: If recursive calls are used in the C/C++ source program, first determine the stack area 
required for a recursive call, and then multiply the size with the maximum number of 
recursive calls. 


Heap Area: The total heap area required is equal to the sum of the areas to be allocated by 
memory management library functions (calloc, malloc, realloc, or new) in the C/C++ program. 
An additional 12 bytes must be summed for one call because a 12-byte management area is used 
every time a memory management library function allocates an area. 


The compiler controls heap area in units of 1024 bytes. Area size allocated for the heap area 
(HEAPSIZE) is calculated by the following equation. 
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HEAPSIZE = 1024 xn (n> 1) 
(Area size allocated by the memory control library) + control area size < HEAPSIZE 


An I/O library function uses memory management library functions for internal processing. The 
size of the area allocated in an input/output is determined by the following formula: 516 bytes x 
(maximum number of simultaneously open files) 


Note: Areas released by the free or delete function, which is a memory management library 
function, can be reused. However, since these areas are often fragmented (separated from 
one another), a request to allocate a new area may be rejected even if the net size of the 
free areas is sufficient. To prevent this, take note of the following: 

1. If possible, allocate the largest area first after program execution is started. 


2. If possible, make the data area size to be reused constant. 
(3) Rules for Allocating Dynamic Area 


The dynamic area is allocated to RAM. The stack area is determined by specifying the highest 
address of the stack to the vector table, and refer to it as SP (stack pointer). Since the interrupt 
operation of the SH3, SH3E, and SH4 differ from that of the SH1, SH2, and SH2E, interrupt 
handlers are necessary. The heap area is determined by the initial specification in the low-level 
interface routine (sbrk). For details on stack and heap areas, refer to section 3.3.1, Vector Table 
Setting (VEC_TBL), and section 3.4.6, Creating Low-Level Interface Routine, respectively. 
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3.3 Setting the Execution Environment 


This section describes the environment required for C/C++ program execution. A C/C++ program 
environment specification program must be created according to the user system specifications 
because the C/C++ program execution environment differs depending on the user system. In this 
section, basic program execution specification, where no library function is used, is described as 
an example. Refer to section 3.4, Setting the C Library Function Execution Environment, for 
details on using library functions when using C library functions, low-level I/O interface routine, 
or memory allocation routine. 


Figure 3.4 shows an example of program configuration. 


: Required routine 


Lz Required table 


_ INITSCT 


Figure 3.4 Program Configuration (No C Library Function is Used) 


Note: Required if global class objects are declared in C++ program. 
Each routine is described below. 


Vector table setting (VEC_TBL): Sets the vector table so as to initiate register initialization 
program _ _INIT and set the stack pointer (SP) by power-on reset. Since the interrupt operation of 
the SH3, SH3E, and SH4 differ from those of the SH1, SH2, and SH2E, interrupt handlers are 
necessary. 


Initialization (__INIT): Initializes registers and sequentially calls initialization routines. 


Section initialization (__INITSCT): Clears the non-initialized data area with zeros and copies 
the initialized data area in ROM to RAM. 


Global class object initial processing* (__call_init): Calls constructors of class object that is 
declared as global. 
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Global class object post processing* (__call_end): Calls destructors of global class object to be 
destructed after the main function is executed. 


Note: Required if global class objects are declared in C++ source program. 


The following describes how each process is implemented (in the order as described above). 


3.3.1 Vector Table Setting (VEC_TBL) 


To call register initialization routine _ _INIT at power-on reset, specify the start address of 
function _ _INIT at address 0 in the vector table. Also to specify the SP, specify the highest 
address of the stack to address H'4. Since the interrupt operation of the SH3, SH3E, and SH4 
differ from those of the SH1, SH2, and SH2E, interrupt handlers are necessary. When the user 
system executes interrupt handling, interrupt vector settings are also performed in the VEC_TBL 
routine. The coding example of VEC_TBL is shown below. 


Example (SH1, SH2, SH2E): 


.-SECTION VECT, DATA, LOCATE=H'0000 ; Assigns section VECT to address H'0 


; by the SECTION directive. 


. IMPORT _ INIT 

. IMPORT _IRQO 

-DATA.L _ _INIT ; Assigns the start address of _ _INIT to 
; addresses H'0x0 to H'0x3. 

.DATA.L (a) ; Assigns the SP to addresses H'0x4 to H'0x7. 
; (a): The highest address of the stack 

. ORG H'00000100 

.-DATA.L _IRQO ; Assigns the start address of IRQO to 
; addresses H'0x100 to H'0x103 

. END 
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3.3.2 Initialization (__INIT) 


___INIT initializes registers, calls initialization routine sequentially, and then calls the main 
function. The coding example of this routine is shown below. 


Example: 


#ifdef _ cplusplus 


extern"C" { 


#endif 

void _INITSCT (void) ; 
void main (void) ; 

void _call_init (void) ; 
void _call_end(void) ; 
#ifdef __ cplusplus 

} 

#endif 

#ifdef | _ cplusplus 


extern "Cc" 
#endif 
void _INIT() 
{ 
_INITSCT() ; 
/* Calls section initialization routine _ _INITSCT. */ 
_Gall. anit-() ; 
main(); /* Calls main routine main. */ 
_call_end(); 
for 77) 
/* Branches to endless loop after executing main function */ 


/* and waits for reset * / 
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3.3.3 Section Initialization (__INITSCT) 


To set the C/C++ program execution environment, clear the non-initialized data area with zeros 
and copy the initialized data area in ROM to RAM. To execute the _ _INITSCT function, the 
following addresses must be known. 


Start address (1) of initialized data area in ROM 

Start address (2) and end address (3) of initialized data area in RAM 

Start address (4) and end address (5) of non-initialized data area 

Start address (6) and end address (7) of initial processing data area *' in ROM 
Start address (8) and end address (9) of post-processing data area*' in ROM 


(Pi 
ic) 
(Oh 


hitl-procassing data = 
wea (ONT 


Post processing data™! 
wea (0_BYD_) 
Virtual function table7! 
area (C_$UTEL) 


hiidized At area 
(Ri 
Norriritaized 
dats area (Bh 
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To obtain the above addresses, create the following assembly programs and link them together. 


-SECTION D, DATA, ALIGN=4 
-SECTION R, DATA, ALIGN=4 
-SECTION B,DATA,ALIGN=4 

. SECTION D_INIT_,DATA, ALIGN=4** 
- SECTION D_END_,DATA,ALIGN=4** 
-SECTION C,DATA,ALIGN=4 


_ _D_ROM .DATA.L (STARTOF D) 
; Start address of section D (1) 
_ _D_BGN -DATA.L (STARTOF R) 
; start address of section R (2) 
_ _D_END .DATA.L  (STARTOF R) + (SIZEOF R) 
; end address of section R (3) 
_ _B BGN -DATA.L (STARTOF B) 
; start address of section B (4) 
_ _B END .DATA.L  (STARTOF B) + (SIZEOF B) 
; end address of section B (5) 
_ _PRE BGN .DATA.L  (STARTOF D INIT )*? 
; start address of section D_INIT_ (6) 
_ _PRE_ END .DATA.L (STARTOF D_INIT_) + (SIZEOF D_INIT_)** 
; end address of section D_INIT_ (7) 
_ _POST_BGN  .DATA.L  (STARTOF D END )** 
;start address of section D_END_ (8) 
_ _POST_END DATA.L (STARTOF D_END_) + (SIZEOF D_END )*? 
;end address of section D_END_ (9) 

-EXPORT _ _D ROM 

.EXPORT _ _D BGN 

-EXPORT _ _D END 

.EXPORT _ _B BGN 

-EXPORT _ _B END 

-EXPORT _ _PRE BGN 

-EXPORT _ _PRE END 

-EXPORT _ _POST_BGN 

-EXPORT _ _ POST END 

. END 
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The statements marked with *1 are required to compile a program containing global 


2. Section names B and D must be the non-initialized data area and initialized data area 
section or #pragma section. B and 


3. ROM option 


If the above preparation is completed, section initialization routine can be written in C/C++ as 
shown below. 


Section initialization routine 


extern int *_D_ROM, * B BGN, * B END, * D BGN, * D END; 


extern "C" 


#endif 


_B_BGN ; p < _B END ; p++) 
= 0; 


q = _D ROM; p < _D END ; p++, q++) 


Note: The declaration of p and q must be a char* type when the section size is not a multiple of 
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Example: 


Initial processing and post-processing routine for global object 


void (** PRE BGN) ( 
(** PRE END) ( 
void (**POST_BGN) ( 
(** POST_END) ( 


extern "c"{ 


void 


void 


void _call_init(); 
void _call_end(); 


} 


extern "C" void _call_init ( ) 


{ 


void (**ppf) ( ); 


for ( ppf = _PRE_BGN; ppf < _PRE_END; ppf++) 
(*ppf) ( ); /* Calls constructor of global object */ 


extern "C" void _call_end ( ) 


{ 


void (**ppf) ( ); 


for ( ppf = _POST_BGN; ppf < _POST_END; ppf++) 
(App£) € )% /* Calls destructor of global object */ 


Rev. 1.0, 09/98, page 121 of 476 


HITACHI 


3.4 


To use library functions, they must be initialized to set the C/C++ program execution 
environment. To use I/O (stdio.h) and memory allocation (stdlib.h) functions, or to use the library 


created for each system. 


This section describes how to set the C/C++ program execution environment when library 
3.5 shows the program configuration when library functions are used. 


Power - on reset 


1: Table always required 


> Routine aways required 


> Rowine required when library 
i= ued 


Bae [Supplied by the CIC++ com pier 


Figure 3.5 Program Configuration When Library Functions are Used 


Note: declared in C++ program. 


the library function that corresponds to the user system must be created beforehand. For details on 
a program example, refer to ppendix D, Examples of 
a library function assert macro, you must create an abort function first. 


Each routine is required to execute library functions as follows. 


Sets the vector table to initiate register initialization program 
(_ __INIT) and set the stack pointer (SP) at power-on reset. Since the interrupt of the SH3, SH3E, 
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Initializing Registers (__INIT): Initializes registers and sequentially calls the initialization 
routines. 


Initializing Sections (__INITSCT): Clears non-initialized data area with zeros and copies the 
initialized data area in ROM to RAM. 


Initializing Library Functions (__INITLIB): Initializes library functions required to be 
initialized; especially, prepares standard I/O functions. 


Closing Files (__CLOSEALL): Closes all files with open status. 


Low-Level Interface Routine: Interfaces library functions and user system when standard I/O 
and memory management library functions are used. 


Global Class Object Initial Processing (__call_init): Calls a constructor of a class object that is 
declared as global. 


Global Class Object Post-Processing (_ _call_end): Calls a destructor of a global class object 
after the main function is executed. 


Creation of the above routines is described below. 


3.4.1 Vector Table Setting (VEC_TBL) 


Same as when no library function is used. For details, refer to section 3.3, Setting the Execution 
Environment. 


3.4.2 Initializing Registers (__INIT) 


Initializes registers and sequentially calls the initialization routine _ _INITLIB and file closing 
routine _ _CLOSEALL. The coding example of __INIT is shown below. Since the interrupt 
operation of the SH3, SH3E, and SH4 differ from those of the SH1, SH2, and SH2E, interrupt 
handlers are necessary. 


Example: 


#ifdef _ _cplusplus 
extern “Cc” { 

#endif 

void _INITSCT (void) ; 
void _INITLIB(void) ; 
void main(void) ; 
void _CLOSEALL (void) 
void _INIT(void) 
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void call _init(); 
void _call _end(); 
#ifdef | _cplusplus 


} 


#endif 


#ifdef cplusplus 
extern, “C” 

#endif 

void _INIT(void) 


{ 


_INITSCT () 7 /* Calls section initialization routine _ _INITSCT. */ 
_INITLIB() ; /* Calls library initialization routine _ _INITLIB. */ 
_call_init(); /* Calls _ _call_init. * / 
main(); /* Calls C program main function _main. */ 
_call_end() ; /* Calls _ _call_end. * / 
_CLOSEALL () ; /* Calls file close routine _ _CLOSEALL. * / 
for( jf 7 ) /* Branches to endless loop after executing main */ 
? /* function and waits for reset. * / 


3.4.3 Initializing Sections (__INITSCT) 


Same as when the library functions are not used. For details, refer to section 3.3.3, Section 
Initialization (_ __INITSCT). 


3.4.4 Initializing Library Functions (__INITLIB) 


Some library functions must be initialized before being used. The following description assumes 
the case when the initialization is performed in ___INITLIB in the program initiation routine. 


To perform initialization, the following must be considered. 


erro indicating the library error status must be initialized for all library functions. 

2. When using each function of <stdio.h> and assert macro, standard I/O library function must be 
initialized. The low-level interface routine must be initialized according to the user low-level 
initialization routine specification if required. 


3. When using the rand and strtok functions, library functions other than the standard I/O must be 
initialized. 
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Library function initialization program example is shown below. 
Example: 


#include <errono.h> 

#ifdef _ cplusplus 

extern “Cc” { 

#endif 

void _INIT_LOWLEVEL(void) ; 
void _INIT_IOLIB(void) ; 
void _INIT OTHERLIB(void) ; 
#ifdef _cplusplus 

} 


#endif 


#ifdef | _ cplusplus 


extern “C” 


#endif 
void _INITLIB(void) /* Deletes an underline from symbol name */ 
/* used in the assembly routine */ 
{ 
errno=0; /* Initializes library functions commonly */ 
_INIT_LOWLEVEL( ) ; /* Calls low-level interface * / 
/* initialization routine */ 
_INIT_IOLIB( ) ; /* Calls standard I/O initialization */ 
/* routine * / 
_INIT_OTHERLIB( ) ; /* Calls initialization routine other */ 
/* than that for standard I/O */ 


The following shows examples of initialization routine (_INIT_IOLIB) for standard I/O library 
function and initialization routine (_INIT_OTHERLIB) for other standard library function. 
Initialization routine (.INIT.LOWLEVEL) for low-level interface routine must be created 
according to the user low-level interface routine's specifications. 
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(1) Creating Initialization Routine (_INIT_IOLIB) for Standard I/O Library Function 


The initialization routine for standard I/O library function initializes FILE-type data used to 
reference files and open the standard I/O files. The initialization must be performed before 
opening the standard I/O files (figure 3.6). 


The following shows an example of _INIT_IOLIB. 
Example: 


#include <stdio.h> 
#ifdef | _cplusplus 
extern, “ct 

#endif 

void _INIT_IOLIB (void) 


{ 


FILE *fp ; 


/*Initializes FILE-type data*/ 


for (fp=_iob; fp<_iob+ NFILE; fp++) { 


fp -> _bufptr=NULL ; /*Clears buffer pointer */ 
fp -> _bufent=0 ; /*Clears buffer counter * / 
fp -> _buflen=0 ; /*Clears buffer length */ 
fp -> _bufbase=NULL ; /*Clears base pointer * / 
fp -> _ioflagl=0 ; /*Clears I/O flag * / 


fp -> _ioflag2=0 ; 
fp -> _i1ofd=0 ; 


/*Opens standard I/O file */ 


if (freopen ( "stdin"**, "rr", stdin) ==NULL) /*Opens standard input file * / 
stdin->_ioflagl=Oxff ; /*Disables file access*’ */ 
stdin-> ioflagl |= _IOUNBUF ; /*No data buffering*? */ 


if (freopen ( "stdout"*?, "w", stdout) ==NULL) /*Opens standard output file */ 
stdout-> ioflagl=Oxff ; 
stdout->_ioflagl |= _IOUNBUF ; 


if (freopen( "stderr"**, "w", stderr)==NULL) /*Opens standard error file */ 
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stderr-> ioflagl=Oxff ; 


stderr->_ioflagl |= _IOUNBUF 


! 


Notes: 1. Standard I/O file names are specified. These names are used by the low-level interface 
routine open. 


2. If file could not be opened, the file access disable flag is set. 


For equipment that can be used in interactive mode such as a console, the buffering 
disable flag is set. 


/*Declares FILE-type data in the C/C++ language*/ 


#define NFILE 20 

struct _iobuf{ 
unsigned char * bufptr; /*Buffer pointer */ 
long _bufent; /*Buffer counter */ 
unsigned char * bufbase; /*Buffer base pointer */ 
long _buflen; /*Buffer length */ 
char _ioflagl; /*I/O flag */ 
char _ioflag2; /*I/O flag */ 
char _iofd; /*I/O flag */ 

}_iob [_NFILE] ; 


Figure 3.6 FILE-Type Data 
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(2) Creating Initialization Routine (INIT_OTHERLIB) for Other Library Function 


The following shows an example of initial setting program of C library function (rand function 


Example: 


#include <stddef.h> 


extern void srand(unsigned int) ; 


#ifdef _— cplusplus 


#endif 


void _INIT OTHERLIB (void) 


srand(1) ; /*Sets initial value when rand function is used */ 
*/f 
[* */ 
} 
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3.4.5 Closing Files (__CLOSEALL) 


is stored in a memory buffer. When the buffer becomes full, data is output to an external storage 
device. Therefore, if the files are not closed, data remaining in buffers is not output to external 


When an program is installed in a device and executed, the program will not end unless it finishes 
its operation. However, if the main function is terminated by a program error, all open files must 


The following shows an example of _ CLOSEALL. 


Example: 


#ifdef cplusplus 


extern *C” 


void _CLOSEALL (void) /* Deletes an underscore character * / 


*/f 


for (i=0; i<_NFILE; i++) 


/*Checks that file is open*/ 


/*Closes open files*/ 


fclose(& iob[i]) ; 
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3.4.6 Creating Low-Level Interface Routines 


Low-level interface routines must be supplied for C/C++ programs that use the standard 
input/output or memory management library functions. Table 3.2 shows the low-level interface 
routines used by standard library functions. 


Table 3.2. Low-Level Interface Routines 


Name Explanation 

open Opens a file 

close Closes a file 

read Reads data from a file 

write Writes data to a file 

Iseek Sets the file read/write position for data 
sbrk Allocates a memory area 


Refer to the attached Standard Library Memory Stack Size Listing for details on low-level 
interface routines required for each library function. 


Initialization of low-level interface routines must be performed when the program is started. For 
more information, see the explanation concerning the _INIT_.LOWLEVEL function in section 
3.4.4, Initializing Library Functions (__INITLIB). 


The rest of this section explains the basic concept of low-level input and output, and gives the 
specifications for each interface routine. Refer to appendix E, Examples of Creating Low-Level 
Interface Routines, for details on the low-level interface routines that run on the SuperH RISC 
engine simulator debugger. 


(1) Concept of I/O Operations 


Standard input/output library functions manage files using the FILE-type data. Low-level 
interface routines manage files using file numbers (positive integers) which correspond directly to 
actual files. 


The open routine returns a file number for a given file name. The open routine must determine the 
following, so that other functions can access information about a file using the file number: 


e File device type (console, printer, disk, etc.) 


(For a special device such as a console or printer file, the user chooses a specific file name that 
can be recognized uniquely by the open routine.) 


e Information such as the size and start address of the buffer used for the file 
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e Fora disk file, the offset (in bytes) from the beginning of the file to the next read/write 
position 


for read/write operations is determined by the lseek routine according to the information 
determined by the open routine. 


the areas of memory allocated by the open routine to be reused. 


(2) Low-Level Interface Routine Specifications 


actual interfaces and explains their operations, and notes on implementation. 


The interface for each routine is shown using the format below. 


Note: Function names o 
interface routines. Do not use these names in user program. 


Example: 


Routine name) 


Purpose (Purpose of the routine) 
Interface (Shows the interface as a C function declaration) 
(To declare as a routine C++ program, add extern "C") 
Parameters No. Name Type Meaning 
1 (Parameter name) (Parameter type) (Meaning of the parameter) 
Return value Type (Type of return value) 
Normal (Return value for normal termination) 
Abnormal (Return value for abnormal termination) 
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open routine 


Purpose Opens a file 
Interface int open (char *name, 
int mode) ; 
Parameters No. Name Type Meaning 
1 name Pointer to char String literal indicating a file name 
2 mode int Processing specification at file 
opening 
Return value Type int 
Normal File number of the file opened 
Abnormal -1 


Explanation: The open routine opens the file specified by the first parameter (file name) and 
returns a file number. The open routine must determine the file device type (console, printer, disk, 
etc.) and assign this information to the file number. The file type is referenced using the file 
number each time a read/write operation is performed. 


The second parameter (mode) gives processing specifications for the file. The effect of each bit of 
this parameter is explained as follows: 


cs B432i10 
ede] 


O_LRDONLY 
O_WRONLY 
O_RDWR 
O_OREATE 
O_TRUNG 
O_LAPPEND 


Description: 


O_RDONLY (bit 0) 

If this bit is 1, the file becomes read only. 
O_WRONLY (bit 1) 

If this bit is 1, the file becomes write only. 
O_RDWR (bit 2) 

If this bit is 1, the file becomes read/write. 
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(4) O_CREATE (bit 3) 
If this bit is 1 and the file indicated by the file name does not exist, a new file is created. 

(5) O_TRUNC (bit 4) 
If this bit is 1 and the file indicated by the file name exists, the file contents are discarded and 
the file size is set to zero. 

(6) O_APPEND (bit 5) 
If this bit is 1, the read/write position is set to the end of the file. If this bit is 0, the read/write 
position is set to the beginning of the file. 


An error is assumed if the file processing specifications contradict with the actual characteristics 
of the file. 


The open routine returns a file number (positive integer) which can be used by the read, write, 
lseek, and close routines, provided the file opens normally. The relationship between file numbers 
and actual files must be managed by the low-level interface routines. The open routine returns a 
value of —1 if the file fails to open properly. 
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close routine 


Purpose Closes a file 
Interface int close(int fileno) ; 
Parameters No. Name Type Meaning 
1 fileno int File number of the file to be closed 
Return value Type int 
Normal 0 
Abnormal —1 


Explanation: The file number, determined by the open routine, is given as the parameter. 

Release the area of memory allocated by the open routine for file management information, so that 
it can be reused. If buffers are used, the contents are output to their corresponding files. Zero is 
returned if the file closes normally. Otherwise, —1 is returned. 
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read routine 


Purpose Reads data from a file 


Interface int read (int fileno, 
char *buf, 
unsigned int count) ; 


Parameters No. Name Type Meaning 
1 fileno int File number of the file to be read 
2 buf Pointer to char Area to be used to store the read data 
3 count unsigned int Byte length of data to be read 
Return value Type int 
Normal Byte length of the data actually read 
Abnormal -1 


Explanation: The read routine loads data from the file indicated by the first parameter (fileno) 
into the area indicated by the second parameter (buf). The amount of data to be read is indicated 
by the third parameter (count). If an end of file is encountered during a read, less than the 
specified number of bytes are read. The file read/write position is updated using the byte length of 
the data actually read. If data is read normally, the routine returns the number of bytes of the data 
read. Otherwise, the read routine returns a value of —1. 
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write routine 


Purpose Writes data to a file 
Interface int write (int fileno, 
char *buf, 


unsigned int count) ; 


Parameters No. Name Type Meaning 

1 fileno int File number 

2 buf Pointer to char Area storing data to be written in the 

file 

3 count unsigned int Byte length of the data to be written 
Return value Type int 

Normal Byte length of the data actually written 

Abnormal —1 


Explanation: The write routine outputs data, whose byte length is indicated by the third 
parameter (count), from the area indicated by the second parameter (buf) into the file indicated by 
the first parameter (fileno). If the device (such as a disk) where a file is stored becomes full, data 
less than the specified byte length is written to the file. If zero is returned as the byte length of 
data actually written several times, the routine assumes that the device is full and sends a return 
value of -1. The file read/write position is updated using the byte length of data actually written. 
If the routine ends normally, it returns the byte length of data actually written. Otherwise, the 
routine returns a value of —1. 
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Iseek routine 
Purpose 


Interface 


Parameters 


Return value 


Determines the next read/write position in a file 


long lseek (int fileno, 


No. Name 
1 fileno 
offset 


base 


Type 


Normal 


Abnormal 


long offset, 


int base); 
Type Meaning 
int File number of the target file 
long Offset in bytes from specified point in the file 
int Base used for offset (bytes) 
long 


The offset (bytes) from the beginning of the file for the next 
read/write position 


1 


Explanation: The lseek routine determines the next read/write position as an offset in bytes. The 
next read/write position is determined according to the third parameter (base) as follows: 


1. Base =0 


The second parameter gives the new offset relative to the beginning of the file. 


2. Base = 1 


The second parameter is added to the current position to give the new offset. 


3. Base =2 


The second parameter is added to the file size to give the new offset. 


An error occurs if the file is on an interactive device (such as a console or printer), the new offset 
value is negative, or the new offset value exceeds the file size in the case of 1 or 2, above. 


If lseek correctly determines a new file position, the new offset value is returned. This value 
indicates the new read/write position relative to the beginning of the file. Otherwise, the lseek 
routine returns a value of —1. 
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sbrk routine 


Purpose Allocates a memory area 
Interface char *sbrk (unsigned long size) ; 
Parameters No. Name Type Meaning 
1 size unsigned long Size of the area to be allocated (in 
bytes) 
Return value Type Pointer to char 
Normal Start address of the allocated area 
Abnormal (char *) — 1 


Explanation: The size of the area to be allocated is given as a parameter. Create the sbrk routine 
so that consecutive calls allocate consecutive areas beginning with the lowest available address. 
An error will occur if there is insufficient memory. If the routine ends normally, it returns the start 
address of the allocated area. Otherwise, the routine returns (char *) — 1. 


Rev. 1.0, 09/98, page 138 of 476 
HITACHI 


Section 4 Error Messages 


4.1 Error Messages 


This section gives lists of error messages in order of error number. A list of error messages are 
provided for each level of errors (I = Information error, W=Warning error, E = Error, F = Fatal 
error, or (—) = Internal error) in the format below. 


Error number (Error Level: I, W, E, F, or (—)) Error Message 


0001 = (1) "string" in comment 


String literal "string" exists in comment. 


0002 = (1) No declarator 


A declaration without a declarator exists. 


0003 = (1) Unreachable statement 


A statement that will not be executed exists. 


0004 ~=(d) Constant as condition 


A constant expression is specified as condition for if or switch statement. 


0005 ~=—s (X) Precision lost 


Precision may be lost when assigning with type conversion a right hand side value to the left hand 
side value. 


0006 =X) Conversion in argument 


A function parameter expression is converted into a parameter type specified in the prototype 
declaration. 


0008 = (1) Conversion in return 


A return statement expression is converted into a value type that should be returned from a 
function. 


0010 (1) Elimination of needless expression 


A needless expression exists. 


0011 (1) Used before set symbol: "variable name" 
A variable is used before setting its value. 


0012 ~=(d) Unused variable "variable name" 


An unused variable exists. 
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0015 = (1) No return value 


A return statement is not returning a value in a function that should return a type other than the 
void type, or a return statement does not exist. 


0100 (Xd) Function "function name" not optimized 
A function which is too large cannot be optimized. 


0200 (1) No prototype function 


There is no prototype declaration. 


1000 (W) Illegal pointer assignment 
A pointer is assigned to a pointer with a different data type. 


1001 (W) Illegal comparison in "operator" 
The operands of the binary operator == or != are a pointer and an integer other than 0. 


1002 (W) Illegal pointer for "operator" 


The operands of the binary operator ==, !=, >, <, >=, or <= are pointers assigned to different types. 


1005 (W) Undefined escape sequence 


An undefined escape sequence (a character following a backslash) is used in a character constant 
or string literal. 


1007. (W) Long character constant 
A character constant consists of two or more characters. 


1008  (W) Identifier too long 
An identifier's length exceeds 250 characters. 


1010 (W) Character constant too long 


A character constant consists of four or more characters. 


1012 = (W) Floating point constant overflow 


The value of a floating-point constant exceeds the limit. Assumes the internally represented value 
corresponding to +o or —co depending on the sign of the result. 


1013. = (W) Integer constant overflow 


The value of unsigned long integer constant exceeds the limit. Assumes a value ignoring the 
overflown upper bits. 


1014 =(W) Escape sequence overflow 


The value of an escape sequence indicating a bit pattern in a character constant or string literal 
exceeds 255. The low order byte is valid. 
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1015 = (W) Floating point constant underflow 


The absolute value of a floating-point constant is less than the lower limit. Assumes 0.0 as the 
value of the constant. 


1016 (W) Argument mismatch 


The data type assigned to a pointer specified as a formal parameter in a prototype declaration 
differs from the data type assigned to a pointer used as the corresponding actual parameter in a 
function call. Uses the internal representation of the pointer used for the function call actual 
parameter. 


1017. = (W) Return type mismatch 


The function return type and the type in a return statement are pointers but the data types assigned 
to these pointers are different. Uses the internal representation of the pointer specified in the 
return statement expression. 


1019 (W) Illegal constant expression 


The operands of the relational operator <, >, <=, or >= in a constant expression are pointers to 
different data types. Assumes 0 as the result value. 


1020  (W) Illegal constant expression of "-"' 


The operands of the binary operator - in a constant expression are pointers to different data types. 
Assumes 0 as the result value. 


1021 (W) Register saving pragma conflicts in interrupt function "function name" 


Invalid #pragma that controls saving or recovery of register contents corresponding to an interrupt 
function indicated by a function name. #pragma is ignored. 


1022 (W) First operand of operator is not lvalue 


The first operand operator cannot be the lvalue. 


1023  (W) Can not convert Japanese code "code" to output type 
A Japanese code "code" cannot be converted to the specified output code. 


1200 = (W) Division by floating point zero 


Division by the floating-point number 0.0 is carried out in a constant expression. Assumes the 
internal representation value corresponding to +eo or —co depending on the sign of the operands. 


1201 (W) Ineffective floating point operation 


Invalid floating-point operations such as c - co or 0.0 / 0.0 are carried out in a constant expression. 


Assumes the internal representation value corresponding to a not a number indicating the result of 
an ineffective operation. 
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1300 (W) Command parameter specified twice 
The same compiler option is specified more than once. Uses the last specified compiler option. 


1301 = (W) "browser" option ignored 
The browser option is specified for C compilation. The compiler ignores the browser option. 


1302 =(W) "double=float" option ignored 


"double=float" and "cpu=sh4" are specified at the same time. The compiler ignores the 
"double=float" option and assumes that "fpu=single" is specified. 


1400 =(W) Function "function name" in #pragma inline is not expanded 
A function specified using #pragma inline could not be expanded where the function is called. 
Compiling processing continues. 


1500 = =(W) EC++ does not support "class name" 
The "class name" specified in multiple inheritance or virtual base class is not supported by EC++. 


2000 ~=(E) Illegal preprocessor keyword 
An illegal keyword is used in a preprocessor directive. 


2001 (E) Illegal preprocessor syntax 


There is an error in preprocessor directive or in a macro call specification. 


2002 =(E) Missing "," 

A comma (,) is not used to delimit two arguments in a #define directive. 

2003 =(E) Missing ")" 

A right parenthesis ( ) ) does not follow a name in a defined expression. The defined expression 
determines whether the name is defined by a #define directive. 

2004 = (E) Missing ">" 


A right angle bracket (>) does not follow a file name in an #include directive. 


2005 (EE) Cannot open include file "file name" 


The file name specified by an #include directive cannot be opened. 


2006 =(E) Multiple #define's 


The same macro name is redefined by #define directives. 


2008  (E) Processor directive #elif mismatches 


There is no #if, #ifdef, #ifndef, or #elif directive corresponding to an #elif directive. 
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2009 = (E) Processor directive #else mismatches 
There is no #if, #ifdef, or #ifndef directive corresponding to an #else directive. 


2010 (KE) Macro parameters mismatch 


The number of macro call arguments and the number of macro definition arguments are not equal. 


2011 (KE) Line too long 


After macro expansion, a source program line exceeds the compiler limit. 


2012 (KE) Keyword as a macro name 


A preprocessor keyword is used as a macro name in a #define or #undef directive. 


2013 ~=(E) Processor directive #endif mismatches 


There is no #if, #ifdef, or #ifndef directive corresponding to an #endif directive. 


2014 (KE) Missing #endif 
There is no #endif directive corresponding to an #if, #ifdef, or #ifndef directive, and the end of file 
is detected. 


2016 (KE) Preprocessor constant expression too complex 


The total number of operators and operands in a constant expression specified by an #if or #elif 
directive exceeds the limit. 


2017 = (E) Missing " 


A closing double quotation mark (") does not follow a file name in an #include directive. 


2018 (E) Ilegal #line 
The line count specified by a #line directive exceeds the limit. 


2019 (EK) File name too long 
The length of a file name exceeds 128 characters. 


2020 (KE) System identifier "name" redefined 


The name of the defined symbol is the same as that of the run time routine. 


2100 (E) Multiple storage classes 


Two or more storage class specifiers are used in a declaration. 


2101 (EK) Address of register 
An unary-operator & is used for a variable that has a register storage class. 


2102 = (E) Illegal type combination 


A combination of type specifiers is illegal. 
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2103 ~=(E) Bad self reference structure 


A struct or union member has the same data type as its parent. 


2104 = (E) Illegal bit field width 


A constant expression indicating the width of a bit field is not an integer or it is negative. 


2105 (E) Incomplete tag used in declaration 


An incomplete tag name declared with a struct or union, or an undeclared tag name is used in a 
typedef declaration or in the declaration of a data type not assigned to a pointer or to a function 
return value. 


2106 ~=(E) Extern variable initialized 


A compound statement specifies an initial value for an extern storage class variable. 


2107 = (E) Array of function 


An array with a function type is specified. 


2108 (E) Function returning array 
A function with an array return value type is specified. 


2109 (E) Illegal function declaration 


A storage class other than extern is specified in the declaration of a function variable used in a 
compound statement. 


2110 = (E) Illegal storage class 


The storage class in an external definition is specified as auto or register. 


2111 = (E) Function as a member 


A member of a struct or union is declared as a function. 


2112 ~=—(E) Illegal bit field 
A type other than an integer type is specified for a bit field. 


2113 = (E) Bit field too wide 
The width of a bit field is greater than the size (8, 16, or 32 bits) indicated by its type specifier. 


2114 (E) Multiple variable declarations 


A variable name is declared more than once in the same scope. 


2115 (E) Multiple tag declarations 


A struct, union, or enum tag name is declared more than once in the same scope. 
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2117 (KE) Empty source program 


There are no external definitions in the source program. 


2118 (KE) Prototype mismatch "function name" 
A function type differs from the one specified in the declaration. 


2119 (EK) Not a parameter name "parameter name" 


An identifier not in the function parameter list is declared as a parameter. 


2120 = (E) Illegal parameter storage class 


A storage class other than register is specified in a function parameter declaration. 


2121 ~=— (BE) Illegal tag name 


The combination of a struct, union, or enum with tag name differs from the declared combination. 


2122 ~=—(E) Bit field width 0 
The width of a bit field specifying a member name is 0. 


2123 (EK) Undefined tag name 
An undefined tag name is specified in an enum declaration. 


2124 ~=(E) Illegal enum value 


A non-integral constant expression is specified as a value for an enum member. 


2125 = (E) Function returning function 


A function with a function type return value is specified. 


2126 = (E) Illegal array size 


The value specifying the number of array elements is not an integer and out of range of | to 
2147483647. 


2127 = (E) Missing array size 


The number of elements in an array is not specified where it is required. 


2128 = (E) Illegal pointer declaration for "'*" 


A type specifier other than const or volatile is specified following an asterisk (*), which indicates 
a pointer declaration. 


2129 = (E) Illegal initializer type 


The initial value specified for a variable is not a type that can be assigned to a variable. 


2130 = (E) Initializer should be constant 


A value other than a constant expression is specified as either the initial value of a struct, union, or 
array variable or as the initial value of a static variable. 
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2131 (EE) No type nor storage class 


Storage class or type specifiers is not given in an external data definition. 


2132 (E) No parameter name 


A parameter is declared even though the function parameter list is empty. 


2133 + (E) Multiple parameter declarations 


Either a parameter name is declared in a macro function definition parameter list more than once 
or a parameter is declared inside and outside the function declarator. 


2134 = (E) Initializer for parameter 


An initial value is specified in the declaration of a parameter. 


2135 = (E) Multiple initialization 


A variable is initialized more than once. 


2136 (E) Type mismatch 
An extern or static storage class variable or function is declared more than once with different data 
types. 


2137  ~=(E) Null declaration for parameter 


An identifier is not specified in the function parameter declaration. 


2138 (E) Too many initializers 


The number of initial values specified for a struct, union, or array is greater than the number of 
struct members or array elements. This error also occurs if two or more initial values are specified 
when the first members of a union are scalar. 


2139 (EE) No parameter type 
A type is not specified in a function parameter declaration. 


2140 (BE) Illegal bit field 


A bit field is used in a union. 


2141 ~~ (E) Struct has no member name 
The member name of a struct is not specified. 


2142 = (E) Illegal void type 

void is used illegally. void can only be used in the following cases: 
1. To specify a type assigned to a pointer 

2. To specify a function return value type 


3. To explicitly specify that a function whose prototype is declared does not have a parameter 
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2143 = (E) IIlegal static function 


There is a function declaration with a static storage class function that has no definition in the 
source program. 


2144 (KE) Type mismatch 


Variables or functions with the same name which have an extern storage class are assigned to 
different data types. 


2145 (EK) Const/volatile specified for incomplete type 
An incomplete type is specified as a const or volatile type. 


2200 = (E) Index not integer 


An array index expression type is not an integer. 


2201 (KE) Cannot convert parameter "n" 


The n-th parameter of a function call cannot be converted to the type of parameter specified in the 
prototype declaration. 


2202 (KE) Number of parameters mismatch 


The number of parameters for a function call is not equal to the number of parameters specified in 
the prototype declaration. 


2203 = (E) Illegal member reference for "'." 


The expression to the left-hand side of the (.) operator is not a struct or union. 


2204 (EK) Illegal member reference for "->"' 


The expression to the left of the -> operator is not a pointer to a struct or union. 


2205  (E) Undefined member name 


An undeclared member name is used to reference a struct or union. 


2206 (E) Modifiable lvalue required for "operator" 


The operand for a prefix or suffix operator ++ or -- has a left value that cannot be assigned (a left 
value whose type is not array or const). 


2207 ~=—(E) Scalar required for '"!" 


The unary operator ! is used on an expression that is not scalar. 


2208 (EE) Pointer required for "*" 


The unary operator * is used on an expression that is not pointer or on an expression of a pointer 
for void. 
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2209 (E) Arithmetic type required for "operator" 


The unary operator + or — is used on a non-arithmetic expression. 


2210 ~=(E) Integer required for "~" 


The unary operator ~ is used on a non-integral expression. 


2211 ~=(E) Illegal sizeof 


A sizeof operator is used for a bit field member, function, void, or array with an undefined size. 


2212 ~—_(E) Illegal cast 


Either array, struct, or union is specified in a cast operator, or the operand of a cast operator is 
void, struct, or union and cannot be converted. 


2213 ~=(E) Arithmetic type required for "operator" 


The binary operator *, /, *=, or /= is used in an expression that is not an arithmetic expression. 


2214 (E) Integer required for "operator" 


The binary operator <<, >>, &, |, *, %, <<=, >>=, &=, |=, “=, or %= is used in an expression that 
> > | > +] 
is not an integer expression. 


2215 = (E) Illegal type for "+" 


The combination of operand types used with the binary operator + is not allowed. 


2216 = (E) Illegal type for parameter 
Type void is specified for a function call parameter type. 


2217 ~=— (E) Illegal type for "-" 
The combination of operand types used with the binary operator - is not allowed. 


2218 (KE) Scalar required 


The first operand of the conditional operator ?: is not a scalar. 


2219  (E) Type not compatible in '"'?:" 


The types of the second and third operands of the conditional operator ?: do not match with each 
other. 


2220 (E) Modifiable Ilvalue required for "operator" 


An expression whose left value cannot be assigned (a left value whose type is not array or const) is 
used as an operand of an assignment operator =, *=, /=, %=, t=, =, <<=, >>=, &=, “=, or | =. 


2221 = (E) Illegal type for "operator" 


The operand of the suffix operator ++ or -- is a pointer assigned to function type, void type, or to a 
data type other than scalar type. 
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2222 (E) Type not compatible for "=" 


The operand types for the assignment operator = do not match. 


2223 (EK) Incomplete tag used in expression 


An incomplete tag name is used for a struct or union in an expression. 


2224 = (E) Illegal type for assign 
The operand types of the assignment operator += or -= are illegal. 


2225  (E) Undeclared name "name" 


An undeclared name is used in an expression. 


2226 ~=(E) Scalar required for "operator" 


The binary operator && or || is used in a non-scalar expression. 


2227 ~—(E) Illegal type for equality 


The combination of operand types for the equality operator == or != is not allowed. 


2228 = (E) Illegal type for comparison 


The combination of operand types for the relational operator >, <, >=, or <= is not allowed. 


2230 = (E) Illegal function call 


An expression which is not a function type or a pointer assigned to a function type is used for a 
function call. 


2231 = (KE) Address of bit field 
The unary operator & is used on a bit field. 


2232 = (E) Illegal type for "operator" 


The operand of the prefix operator ++ or -- is a pointer assigned to a function type, void type, or to 
a data type other than scalar type. 


2233 ~—(E) Illegal array reference 


An expression used as an array is an array or a pointer assigned to a data type other than a function 
or void. 


2234  ~=(E) Illegal typedef name reference 


A typedef name is used as a variable in an expression. 


2235 ~— (E) Illegal cast 
An attempt is made to cast a pointer with a floating-point type. 
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2236 = (E) Illegal cast in constant 
In a constant expression, an attempt is made to cast a pointer with a char or short type. 


2237 ~—(E) Illegal constant expression 


In a constant expression, a pointer constant is cast with an integer and the result is manipulated. 


2238  (E) Lvalue or function type required for "&" 
The unary operator & is not used on the lvalue or is used in an expression other than function type. 


2300 = (EK) Case not in switch 
A case label is specified outside a switch statement. 


2301 = (E) Default not in switch 


A default label is specified outside a switch statement. 


2302 (E) Multiple labels 
A label name is defined more than once in a function. 


2303 = (E) Illegal continue 
A continue statement is specified outside a while, for, or do statement. 


2304 (E) Illegal break 


A break statement is specified outside a while, for, do, or switch statement. 


2305 ~=(E) Void function returns value 


A return statement specifies a return value for a function with a void return type. 


2306 ~=(E) Case label not constant 
A case label expression is not an integer constant expression. 


2307 (KE) Multiple case labels 
Two or more case labels with the same value are used for one switch statement. 


2308 (KE) Multiple default labels 
Two or more default labels are specified for one switch statement. 


2309 (E) No label for goto 
There is no label corresponding to the destination specified by a goto statement. 


2310 (EK) Scalar required 


The control expression (that determines statement execution) for a while, for, or do statement is 
not a scalar. 
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2311 (EE) Integer required 

The control expression (that determines statement execution) for a switch statement is not an 
integer. 

2312 ~=(E) Missing ( 


The control expression (that determines statement execution) does not follow a left parenthesis 
(() for an if, while, for, do, or switch statement. 


2313 = (E) Missing ; 


A do statement is ended without a semicolon (;). 


2314 = (E) Scalar required 


A control expression (that determines statement execution) for an if statement is not a scalar. 


2316 (E) Illegal type for return value 


An expression in a return statement cannot be converted to the type of value expected to be 
returned by the function. 


2400 ~=(E) Illegal character "character" 
An illegal character is detected. 


2401  (E£) Incomplete character constant 


An end of line indicator is detected in the middle of a character constant. 


2402 (E) Incomplete string 
An end of line indicator is detected in the middle of a string literal. 


2403 (E) EOF in comment 
An end of file indicator is detected in the middle of a comment. 


2404 = (E) Illegal character code "character code" 


An illegal character code is detected. 


2405 = (E) Null character constant 


There are no characters in a character constant (i.e., no characters are specified between two 
quotation marks). 


2406 =(E) Out of float 
The number of significant digits in a floating-point constant exceeds 17. 


2407 ~=(E) Incomplete logical line 


A backslash (\) or a backslash followed by an end of line indicator (\ (RET) ) is specified as the 
last character in a non-empty source file. 
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2408 (EK) Comment nest too deep 
The nesting level of the comment exceeds the limit of 255 level. 


2500 = (E) Illegal token "phrase" 


An illegal token sequence is used. 


2501 ~=(E) Division by zero 


An integer is divided by zero in a constant expression. 


2600 =(E) String literal(s) 
An error message specified by string literal #error is output to the list file if nolist option is not 
specified. 


2650 ~=—(E)/) Invalid pointer reference 


The specified address does not match the boundary alignment value. 


2700 = (E) Function "function name" in #pragma interrupt already declared 


A function specified in an interrupt function declaration #pragma interrupt has been declared as a 
normal function. 


2701 (FE) Multiple interrupt for one function 


An interrupt function declaration #pragma interrupt has been declared more than once for the same 
function. 


2702 (FE) Multiple #pragma interrupt options 


The same type of interrupt is declared more than once. 


2703 ~— (E+) Illegal #pragma interrupt declaration 


An interrupt function declaration #pragma interrupt is specified incorrectly. 


2704 ~=(E) Illegal reference to interrupt function 


The interrupt function is referenced incorrectly. 


2705 ~— (E+) Illegal parameter in interrupt function 


Argument types to be used for an interrupt function do not match. 


2706 (E) Missing parameter declaration in interrupt function 


There is no declaration for a variable to be used for an optional specification of an interrupt 
function. 


2707 = (E) Parameter out of range in interrupt function 


The parameter value tn of an interrupt function exceeds the limit of 256. 
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2709 = (E) Illegal section name declaration 


The #pragma section specification is illegal. 


2710 = (E) Section name too long 


The specified section name exceeds the limit of 31 characters. 


2711 = (E) Section name table overflow 


The number of section specified in one file exceeds the limit of 64. 


2712  (E) GBR based displacement overflow 


The variable declared in #pragma gbr_base overflows. 


2713 ~=— (E) Illegal #pragma interrupt function type 
The function type specified #pragma interrupt in illegal. 


2800  (E) Illegal parameter number in in-line function 


Parameters to be used for an intrinsic function do not match. 


2801 (EE) Illegal parameter type in in-line function 
There are different parameter types in an intrinsic function. 


2802  (E) Parameter out of range in in-line function 


A parameter exceeds the range that can be specified by an intrinsic function. 


2803 = (E) Invalid offset value in in-line function 


An argument for an intrinsic function is specified incorrectly. 


2804 = (E) Illegal in-line function 


An intrinsic function that cannot be used by the specified cpu option exists. 


2805 = (E) Function "function name" in #pragma inline/inline_asm already declared 


The function indicated by a function name exists before the #pragma specification. 


2806 (E) Multiple #pragma for one function 


Two or more #pragma directives are specified for one function incorrectly. 


2807 ~— (E) Illegal #pragma inline/inline_asm declaration 
The #pragma inline or #pragma inline_asm is specified illegally. 


2808 = (E) Illegal option for #pragma inline_asm 


The -code=machinecode option is specified in addition to the #pragma inline_asm 
specification declaration. 
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2809 = (E) Illegal #pragma inline/inline_asm function type 
An identifier type that specifies #pragma inline or #pragma inline_asm is illegal. 


2810 (KE) Global variable "variable name" in #pragma gbr_base/gbr_basel already 
declared 


A variable definition indicated by variable name exists before #pragma specification. 


2811 (E) Multiple #pragma for one global variable 


Two or more #pragma directives are specified for one variable incorrectly. 


2812 ~=(E) Illegal #pragma gbr_base/gbr_basel declaration 
The #pragma gbr_base or #pragma gbr_basel specification is illegal declaration. 


2813 = (E) Illegal #pragma gbr_base/gbr_basel global variable type 
An identifier type that specifies #pragma gbr_base or #pragma gbr_basel is illegal. 


2814 = (E) Function "function name" in #pragma noregsave/noregalloc/regsave already 
declared 


The function indicated by a function name exists before the #pragma specification declaration. 


2815 =(E) Illegal #pragma noregsave/noregalloc/regsave declaration 


The #pragma noregsave, or #pragma noregalloc, or #pragma regsave specification is illegal. 


2816 = (E) Illegal #pragma noregsave/noregalloc/regsave function type 


An identifier type that specifies #pragma noregsave, #pragma noregalloc, or #pragma regsave is 
illegal. 


2817 (E) Symbol "identifier" in #pragma abs16 already declared 


A name indicated by an identifier exists before the #pragma specification declaration. 


2818  (E) Multiple #pragma for one symbol 


More than one #pragma is incorrectly specified for one identifier. 


2819  (E) Illegal #pragma abs16 declaration 
The #pragma abs16 specification is illegal declaration. 


2820 (E) Illegal #pragma abs16 symbol type 
An identifier type that specifies #pragma abs 16 is illegal. 


2821 (EE) Global variable "variable name" in #pragma global_register already declared 
The variable that specifies #pragma global_register has already been specified. 
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2822 (E) Illegal register "register" in #pragma global_register 
The register that specified #pragma global_register is illegal. 


2823 = (E) Illegal #pragma global_register declaration 
The specification method of #pragma global_register is illegal. 


2824 = (E) Illegal #pragma global_register type 
A variable that cannot specify #pragma global_register exists. 


3000 (F) Statement nest too deep 


The nesting level of an if, while, for, do, and switch statements exceeds the limit. The maximum 
number is 32 levels. 


3001 (F) Block nest too deep 


The nesting level of compound statements exceeds the limit. 


3002 = (F) #if nest too deep 
The conditional compilation (#if, #ifdef, #ifndef, #elif, and #else) nesting level exceeds the limit. 


3006 (F) Too many parameters 


The number of parameters in either a function declaration or a function call exceeds the limit. 


3007. =+(F) Too many macro parameters 


The number of parameters in a macro definition or a macro call exceeds the limit. 


3008 (F) Line too long 


After a macro expansion, the length of a line exceeds the limit. 


3009 = (F) String literal too long 


The length of string literal exceeds 512 characters. The length of string literal equals to the 
number of bytes when linking string literals specified continuously. The length of the string literal 
is not the length in the source program but the number of bytes included in the string literal data. 
Escape sequence is counted as one character. 


3010  (F) Processor directive #include nest too deep 


The nesting level of the #include directive exceeds the limit. The maximum level is 30. 


3011  (F) Macro expansion nest too deep 


The nesting level of macro expansion performed by a #define directive exceeds the limit. 
The maximum level is 32. 


3012 (F) Too many function definitions 


The number of function definitions exceeds the limit. 
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3013. = (F) Too many switches 


The number of switch statements exceeds the limit. 


3014 = (F) For nest too deep 


The nesting level of a for statement exceeds the limit. 


3015 = (F) Symbol table overflow 


The number of symbols to be generated by the compiler exceeds the limit. 


3016 = (F) Internal label overflow 


The number of internal labels to be generated by the compiler exceeds the limit. 


3017. ~=—(F) Too many case labels 


The number of case labels in one switch statement exceeds the limit. 


3018  (F) Too many goto labels 


The number of goto labels defined in one function exceeds the limit. 


3019  (F) Cannot open source file "file name" 
A source file cannot be opened. 


3020 = (F) Source file input error "file name" 


A source or include file cannot be read. 


3021 (F) Memory overflow 


The SH compiler cannot allocate sufficient memory to compile the program. 


3022 (F) Switch nest too deep 
The nesting level of a switch statement exceeds the limit. 


3023 (F) Type nest too deep 
The number of types (pointer, array, and function) that qualify the basic type exceeds 16. 


3024 ~=(F) Array dimension too deep 
An array has more than six dimensions. 


3025 ~=— (F) Source file not found 


A source file name is not specified in the command line. 


3026 (F) Expression too complex 
An expression is too complex. 
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3027 ~—(F) Source file too complex 


The nesting level of statements in the program is too deep or an expression is too complex. 


3028  (F) Source line number overflow 


The last source line number exceeds the limit. 


3030 (F) Too many compound statements 


The number of compound statements exceeds the limit. 


3031 = (F) Data size overflow 
The size of an array or a structure exceeds the limit of 2147483647 bytes. 


3100  (F) Misaligned pointer access 


There has been an attempt to refer or specify using a pointer that has an invalid alignment. 


3201 (F) Object size overflow 
The object file size exceeds the limit of 4 Gbytes. 


3202 (F) Too many source lines for debug 
There are too many source line to output debugging information. 


3203 (F) Assembly source line too long 


The assembly source line is too long to output. 


3204 = (F) Illegal stack access 


The size of a stack to be used in a function (including a local variable area, register save area, and 
parameter push area to call other functions) or a parameter area to call the function exceeds 
2 Gbytes. 


3300  (F) Cannot open internal file 

An error occurred due to one of the following causes: 

(1) An intermediate file internally generated by the compiler cannot be opened. 
(2) A file that has the same file name as the intermediate file already exists. 


(3) The number of characters in a path name for a list file specification exceeds the limit of 
128 characters. 


(4) A file which the compiler uses internally cannot be opened. 


3301 (F) Cannot close internal file 


An intermediate file internally generated by the compiler cannot be closed. Make sure the 
compiler is installed correctly. 
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3302  (F) Cannot input internal file 


An intermediate file internally generated by the compiler cannot be read. Make sure the compiler 
is installed correctly. 


3303  (F) Cannot output internal file 


An intermediate file internally generated by the compiler cannot be written. 


3304 (F) Cannot delete internal file 
An intermediate file internally generated by the compiler cannot be deleted. 


3305  (F) Invalid command parameter "option name" 


An invalid compiler option is specified. 


3306 = (F) Interrupt in compilation 


An interrupt generated by a (CNTL) C command (from a standard input terminal) is detected 
during compilation. 


3307. ~=(F) Compiler version mismatch 
File versions specified in the compiler do not match the other file versions. 


3308  (F) Cannot create file ''file name" 


The compiler cannot create necessary files. 


3320 (F) Command parameter buffer overflow 


The command line specification exceeds 256 characters. 


3321 =F) Illegal environment variable 

An error occurred due to one of the following causes: 

1. SHC_LIB was not specified. 

2. A file name was specified incorrectly when SHC_LIB was specified or the number of 
characters in a path name exceeds the limit of 118 characters. 

3. Other than SH-1, SH-2, SH-2E, SH-DSP, SH-3, SH-3E, or SH-4 is set for the environment 
variable SHCPU. 


4. SUC_THP = olivetmio cs eyrty 
4000 — 4999 (—) Internal error 


An internal error occurs during compilation. Report the error occurrence to your local Hitachi 
dealer. 


5001 =(W) Linkage specification ignored for 'static' functions and objects 


In a linkage-specified braces {}, a function declared as static or extern linkage directive of an 
object in ignored. 
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6001 (E) Overloaded function "function name" cannot specify #pragma function 
An overloaded function cannot be specified declared as #pragma. 


6002 (E) Preprocessing numerical token is not floating constant value or integer constant 
value 


A preprocessing numerical token is not a floating-point constant or integer constant. 


6101 (E) Illegal storage class 'auto' 


An auto storage class must be specified in an object declaration in a formal argument or a blocks. 


6102 = (E) Illegal storage class 'register' 


A register storage class must be specified in an object declaration in a formal argument or a block. 


6103  (E) 'static' keyword must be applied to objects, functions and anonymous unions 


An static storage class can only be declared as an object name, a function name, or a union without 
a name. 


6104 (E) Function declaration "function name" cannot have 'static' storage in a block 
A static function cannot be declared in a block. 


6105 = (E) Static linkage specifications for 'name" must agree 
No linkage specifier match their names. 


6106 = (E) Illegal storage class 'extern' 


An extern storage class can only be declared as an object name, a function name, or a union 
without a name. 


6108  (E) Inline member function "function name" must be declared before it is called 
A function must be declared as inline before its member function is called. 


6109  (E) Illegal function specifier 'virtual' 


A virtual specifier can only be declared as a non-static class member function declaration in the 
class definition. 


6110 = (E) Illegal 'typedef' declaration in function definition "name" 
A typedef specifier cannot be declared in a function definition. 


6111 (EK) 'typedef’ "name" cannot redefine other type in the same scope 


A type name declared within a scope cannot be redefined to refer to a different type within the 
same scope. 


6112 (E) Cannot specify 'typedef’ "name" after 'enum' 
An enum name that is declared using typedef cannot be used after an enum prefix. 
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6114 (E) Integral type data is not assigned to an enumeration 


An integer value or result of integer promotion cannot be assigned to an enumeration object. 


6116 (E) Undefined linkage-specification "character string" 
An undefined character string is specified for a linkage. 


6117 = (E) Multiple linkage-specification "name" 


Character strings of linkage specification do not match when a function or object has more than 
one linkage. 


6118 (E)'static' function "function name" with linkage-specification 
There is a declaration as a static function in a function with linkage specifier. 


6119 (E) Multiple 'C' linkage overloaded function "function name" 


More than one overloaded function have a C linkage. 


6120 = (E) Illegal 'void &' type 
A void type cannot be specified as a reference type. 


6123. (EK) Cannot specify a reference to &, to bit-fields, to array or to pointer type 


A reference type, bit field, array type, or pointer type cannot be specified as a reference type. 


6124 = (E) Initial value required for declaration & "name" 


An initial value is not specified for a reference type declaration. 


6128  (E) New type defined in a return type of a function or in a parameter 


A type is declared in a return value or parameter type. 


6129 (KE) Non-static members or 'auto' variables can not be used as default parameters 


A nonstatic member is used for a default parameter. 


6130 (E) Default parameter redefined in function "name" 


A default parameter cannot be redefined in the later declaration. 


6131 (E) Non-default parameters found following default parameters 


There is another parameter which is not a default parameter after the default parameter. 


6133 (E) Overloaded operators cannot have default parameters 


An overloaded operator cannot have a default parameter. 


6139 (EF) Overloaded functions "function name" have the same type of parameters except 
& type 
A function cannot be overloaded because the difference is only the reference type of a parameter. 
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6140 (E) Functions "function name" have same the type of parameters except 
const/volatile type 


A function cannot be overloaded because the difference is only the const/volatile type of a 
parameter. 


6141 (E) Functions "function name" have the same type of parameters except return type 
A function cannot be overloaded because the difference is only the type of a return value. 


6142 (EE) Cannot overload function "function name" 


A function cannot be overloaded because the difference is only whether a member function is 
static or not. 


6143 (EE) Operator overloaded function "function name" does not have correct 
parameters 


An operator function must satisfy one of the following conditions: 
1. amember function 
2. have one or more arguments to a class or enumeration type 


3. have one or more arguments to be referenced to a class or an enumeration type 


6144 (EE) Operator overloaded function "=" is not a nonstatic member function 
operator=() 1s not a nonstatic member function. 


6145 (EE) Operator overloaded function "()" is not a nonstatic member function 
operator()() is not a nonstatic member function. 


6146 (KE) Operator overloaded function "[]" is not a nonstatic member function 


operator[]() is not a nonstatic member function. 


6147  (E) Operator overloaded function "->" returns illegal type value 


operator->() does not return a pointer to a class, or does not return an object or reference to a class 
which defines it. 


6148  (E) Operator overloaded function "->" is not a nonstatic member function 


operator->() is not a nonstatic member function. 


6149  (E) The second parameter of the postfix operator function should have type int 
The second argument of a postfix operator++() or --() is not an integer type. 


6150 (EE) 'const' object should have an initial value 
An initial value is required for a const type object because it does not have an external linkage. 


6151  (E) 'friend' should be specified in a class declaration 
A friend specifier is used outside the class declaration. 
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6152 (EE) 'friend' keyword specified twice 
A friend specifier is used twice. 


6153 = (E) 'inline' keyword specified twice 
An inline specifier is used twice. 


6154 = (E) 'virtual' keyword specified twice 


A virtual specifier is used twice. 


6155 (E) ‘inline’ must be specified for functions 
An inline specifier is used other than as a function. 


6156 (EK) Parameters cannot have ‘inline’ specifier 


An inline specifier is used for a parameter. 


6157  (E) Cannot specify ‘inline' and 'extern' together 


Both of inline and extern specifiers are specified. 


6158 (KE) Object "name" initialized with {} format 
An object that can be initialized in braces {} must satisfy one of the following conditions: 
1. array 


2. class that does not have any private/protected members, base classes, constructors, or virtual 
functions. 


6159 (E) 'typedef’ cannot specify 'friend' 
Both typedef and friend are specified. 


6162 (EE) Cannot declare 'typedef' name qualified by a class 


A typedef declaration name cannot be qualified using a class. 


6163 (E) Missing the number of operator function parameters 


The number of a parameter of the overloading operator is invalid. 


6165 (EF) Operator member function cannot specify 'static' 


An overloading operator cannot be a static member function. 


6166 (EK) Operator function or conversion function has function type 


An overloaded operator function or conversion function is not a function type. 


6167 (KE) Conversion function should be a nonstatic member function 


A conversion function is not a nonstatic member function. 
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6169 (KE) A destructor should be a function type 
A destructor is not a function type. 


6170 (EE) Non-member functions cannot specify 'const' or 'volatile' 


A function other than a member function cannot be specified as a const or volatile. 


6171 (EE) Declarations qualified by a class cannot specify storage class specifier 
A storage class cannot be specified for declaration qualified using a class. 


6172 (E) Cannot declare parameter declarations qualified by a class 
A name qualified for an argument declaration using a class is used. 


6203 (E) Ambiguous name "function name" call 


Ambiguous function name, object name, or type name. 


6209 (E) Array "name" does not have dimension size 


Some dimensions are not specified for an array which is used as a type of a nonstatic member. 


6210 (E) Member declarator be omitted 
A class member declarator cannot be omitted. 


6211 (E) Non-virtual function "function name" cannot specify "=0" 


A pure-specifier =0 cannot be specified. A pure-specifier can only be used at a virtual function 
declaration. 


6212 (E) Member "name" cannot have the same name of that class 


A static data member, enumerator, anonymous union member, or nested class type has the same 
name as that of a class. 


6213  (E) Static member function cannot access "name" 


A static member function can be used for a static member, enumerator, or nested class type. 


6219 (KE) Static data member "name" cannot exist in a local class 


A static data member cannot be declared in a local class. 


6221 (E) Union "name" cannot have virtual functions 
A union cannot have a virtual function. 


6222 (EF) Union "name" cannot have base classes 


A union cannot have a base class. 


6223 (E) Union "name" cannot be a base class 


A union cannot be used as a base class. 
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6224  (E) Union member cannot have a constructor, destructor or class with a user 
defined operator =() 


A class object that has a constructor, destructor, or an overloaded assignment operator exists as a 
member of a union. 


6225 (EE) Union "name" cannot have static data members 


A static data member exists as a member of a union. 


6227  (E) Anonymous union must specify 'static' 


A global anonymous union must be declared static. 


6228 (E) Anonymous union cannot have private and protected members 


A private or protected member exists in an anonymous union. 


6229 (E) Anonymous union cannot have member functions 


A function member exists in an anonymous union. 


6233 (E) Nested class declaration cannot access "name" 


For a nested class declaration, only an object, static member, or enumerator defined in the outer 
class can be used. 


6234 (KE) "name" cannot be specified in a local class declaration 


In a local class declaration, only a type name, static variables, extern variables, extern functions, or 
enumerators can be used. 


6236  (E) Member function "name" should be defined in the local class declaration 


A member function in a local class declaration is not defined in the local class. 


6240 (E) Member "name" defined more than once 
A class member is declared twice. 


6241 (KE) Undeclared member "name" 


A member function that is not defined in a class declaration is defined as a member function 
outside the class. 


6242 (KE) "name" declared multiple 


A name is not given when re-evaluating a class. 


6243 (EK) Undeclared base class "name" 


A class name that is specified in the base class is not defined. 


6244 (EE) Base class "name" defined more than once in the derived class declaration 


A direct base class of a derived class is specified more than twice. 
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6246 (EF) Virtual base class "name" casted to the derived class declaration 


A virtual base class cannot be casted to the derived class. 


6248  (E) Returning type mismatch in virtual function "function name" 


A return type of the virtual function of the base class differs from that of the virtual function of the 
derived class. 


6250 = (E) Illegal 'static' virtual function "function name" 
A virtual function cannot be specified as static. 


6251 (EK) Cannot create abstract class object "name" 


An object of an abstract class cannot be created. 


6254 (KE) Implicit pure virtual function "function name" call 
A pure virtual function need be defined only if it is explicitly qualified called. 


6256 (E) "name" is not a member of the class 


A specified class member is not defined. 


6263 (KE) "name" should be defined as a class or a struct 


A name declared using a class or struct specifier is defined as a different specifier. 


6267 ~=(E) Illegal declaration "name" in type-specifier 


A class, enumeration, or typedef name cannot be declared in type-specifier-list. 


6268 (EF) "function name" cannot have parameters and return value 


A parameter or return type cannot be specified for a conversion function. 


6269 (E) Ambiguous user defined conversion 


Ambiguous conversion function. 


6270 (E) Destructor "function name" cannot have parameters and return value 


A parameter or return type cannot be specified for a destructor. 


6271 (KE) Constructor and destructor cannot have 'const', 'volatile' or 'static' keywords 


A constructor or destructor cannot be specified as const, volatile, or static. 


6272 (KE) Constructor and destructor "function name" does not have addresses 


An address of a constructor and destructor cannot be given. 


6274  (E) The first parameter type of operator new() should be 'size_t' 
The first parameter of a function operator new() of a class must be integer type size_t. 
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6275 (E) The return type of operator new() should be 'void*' 


A return type of a function operator new() which is a member must be a void* type. 


6276 (E) The first parameter type of operator delete() should be 'void*' 
The first argument of a member or global function operator delete() must be a void* type. 


6277 = (E) The return type of operator delete() should be 'void' 
A return type of a ::operator delete() must be a void type. 


6278 (E) Operator delete() function cannot be overloaded 
An operator delete() cannot be overloaded. 


6280 (KE) The second parameter type of operator delete() should be 'size_t' 
The second parameter of a class function operator delete() must be integer type size_t. 


6281 (E) Illegal virtual operator new() or delete() function 
Either operator new() or operator delete() cannot be specified as a virtual function. 


6282 (E) Default constructor required 


An initializer or a corresponding initial value is not valid or a default constructor is not specified 
without an initial value. 


6283 (KE) Class "name" requires a constructor 


Initial settings of a virtual base class are invalid. If a constructor of the most derived class does 
not specify an initial specifier of a member of a virtual base class, the virtual base class which 
must have a default constructor or must not have any constructor. 


6284 (KE) Undefined class member "name" 


Initial settings of a class member are invalid. An object of a class member either must not have 
any constructor or must have a default constructor. Otherwise a class member must be initialized 
in a constructor that declares the class member. 


6285 (EE) Multiple implicit conversion 


More than one conversion function which is used implicitly exists in an expression value. 


6286 (EK) 'public' copy constructor "function name" required 


A copy constructor cannot be accessed because it is declared as a private member. 


6287 (EK) Illegal nonstatic 'const' array initialization 


A member of a nonstatic const array cannot be initialized using a constructor. 


6288 (KE) Constructors cannot initialize indirect base classes or derived members 


An indirect base class or derived member cannot be initialized using a constructor. 
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6289 (EE) Cannot generate default assignment operator 


A default assignment operator cannot be generated. The class has a const member, reference 
member, member of a class that has a private operator=(), or member of a base class that has a 
private operator=(). 


6290 (KE) Cannot generate default copy constructor "name" 


A default copy constructor cannot be generated. A class does not have a name or a member of a 
class or base class has a protected copy constructor, or a normal class does not have a copy 
constructor. 


6291 (EE) Cannot assign "name" 


A base class object cannot be assigned to the derived class object. 


6292 (KE) Cannot access private member "name" 


A private member cannot be referenced. 


6293 (EE) Cannot access protected member "name" 
A protected member cannot be referenced. 


6294 (E) Illegal access declaration "name" 


In an access declaration, an access specification that is declared as a member of a base class 
cannot be changed. 


6296 (EE) Cannot change the access control of overloaded function "function name" 


Overloaded functions which differ in an access specification cannot be modified in an access 
declaration. 


6297 (KE) Cannot change the access control of redefined member "name" 


If a member of a derived class is redefined, a member access of a base class cannot be modified 
using a derived class. 


6298  (E) 'friend' declaration syntax error 


An attempt was made to define a class in a friend declaration. 


6303 (EE) Cannot access base class "class name" 
The base class cannot be accessed. 


6304 (EE) Cannot define 'friend' data members 
A data member is declared as friend. 


6305 = (E) Illegal pure virtual function specifier 
A value other than =0 is specified for a pure virtual function specification. 
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6306 (E) Cannot access class "name" member 


A class member that cannot be accessed is specified. 


6307 (KE) Cannot access base class member "name" 


A base class member cannot be accessed. 


6308  (E) Constructors cannot have return type 


A constructor has a return type. 


6310 (E) Cannot define class member "name" 
A member of a class is declared in a different class. 


6311 = (E) Illegal constructor/destructor declaration 


A constructor/destructor is specified incorrectly. 


6313. (E) Cannot declare nonstatic data member "name" 


A nonstatic data member cannot be redeclared outside the class. 


6314  (E) Illegal data member initializer 
An initial value of a data member is specified incorrectly. 


6401 (E) 'this' should be referred to in a nonstatic member function 


A keyword this can be referenced only in a nonstatic member function. 


6402 (E) "name" does not exist in this file scope 


An identifier following an operator :: does not exist in the file scope. 


6404 = (E) "name" is not a member 
A name following an operator :: is not a member of the class. 


6407 = (E) The type of the second operand of '?:' is different from the third operand 


If the second and third operand types of an operator ?: differ in class, they must have the same 
base class. 


6408 _(E) Base class objects cannot be assigned to derived class objects 


An object of a base class cannot be assigned to an object of a derived class. 


6409 = (E) '?:' operands should have integral types 


A class object or reference cannot be used. 


6417 ~=(E) Illegal type conversion 


For explicit type conversion of a function call, a corresponding constructor is not declared. 
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6421 = (E) Invalid 'new' operand 


Invalid operand of an operator new. 


6425 = =(E) An array cannot be initialized in a 'new' operator 

An array that is specified using an operand of an operator new cannot be initialized using an 
initializer. 

6428  (E) Invalid 'delete' operand 


Invalid operand of an operator delete. 


6430 (E) Cannot convert an object or data to a class object 


An object or value cannot be converted to a class object because a constructor or a conversion 
function is not declared correctly. 


6431 (E) Cannot convert a virtual base class to a derived class 


A virtual base class cannot be casted to a derived class. 


6432 (EK) Illegal explicit type conversion 


A pointer to a member type cannot be converted to a pointer to another member type. 


6433 =(E) '->*' operands type mismatch 
An operand type of an operator ->* does not match. 


6434  (E) The second operand of '->*' and '.*' operator should be a pointer to a member 
of a class 


The second operand of operators ->* and .* must be a pointer to a member type. 


6435 =(E) '.*' operands type mismatch 


An operand type of an operator .* does not match. 


6437  (E) Unary '&' operand require a qualified name 


A qualified-name using an operand of a unary operator & is not a class member name. 


6441 (KE) 'typedef' "name" used as a constructor or a destructor 


A typedef name in a class declared as typedef cannot be used as a constructor or destructor name. 


6442 (EF) Cannot refer to undefined class 


An undefined class cannot be used in an expression. 


6446 (KE) Ambiguous overloaded function call 
Ambiguous overloaded function call. 
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6449 (E) Ambiguous function name referred to 


Ambiguous function name expression which indicates an address of an overloaded function. 


6450 = (E) Illegal function pointer conversion 


A pointer type to a function cannot be converted to a different type. 


6451 = (E) Undeclared function call 
The specified function is not declared. 


6452 = (E) Pointer-to-Member cannot be used as an operand of a function call 
A pointer type to a function cannot be used for a operand other than the function call operand. 


6503 (E) Statements is required in selection statements or iteration statements 


More than one statement must be included in an if or switch statement. In addition, an iterative 
statement must not have a declaration in it. 


6504 = (E) Declaration with initialization is not executed 


A declaration that has an explicit or implicit initializer is jumped. 


6508 (E) Illegal conditional expression 


A conditional statement of a statement while, do, and for must be a class type that can be 
converted to an arithmetic and/or pointer type. 


6513 = (E) Illegal jump 
This is an illegal jump. 


6514 = (E) "xxxx"' is not supported 
There has been an attempt to use a function that is not supported by this version of the compiler. 


7001 (E) Too many identifiers 


The number of identifiers exceeds the limit. 
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4.2 Standard Library Error Messages 


For some library functions, if an error is generated during the library function execution, an error 
number is set in the macro errno defined in the header file <errno.h> contained in the standard 
library. Error messages are defined in the error numbers so that error messages can be output. 
The following shows an example of an error message output program. 


Example: 


#include 
#include 
#include 


#include 


main () 


{ 


FILE *fp; 


<stdio.h> 
<string.h> 
<stdlib.h> 


<errno.h> 


fp=fopen("file", "w"); 


£p=NULL; 
fclose (fp) ; /* error occurred * / 
printf ("%s\n", strerror (errno) ) ; /* print error message */ 
} 
Description: 


1. Since the file pointer of NULL is passed to the felose function as an actual parameter, an error 
will occur. In this case, an error number corresponding to errno is set. 


2. The strerror function returns a pointer of the string literal of the corresponding error message 
when the error number is passed as an actual parameter. An error message is output by 
specifying the output of the string literal of the printf function. 
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Table 4.1 


Error No. 


1100 
(ERANGE) 


1101 
(EDOM) 


1102 
(EDIV) 


1104 
(ESTRN) 


1106 
(PTRERR) 


1200 
(ECBASE) 


1202 
(ETLN) 


1204 
(EEXP) 


1206 
(EEXPN) 


1210 
(EFLOATO) 


1220 
(EFLOATU) 


List of Standard Library Error Messages 


Error Message/Explanation 


Data out of range 
An overflow occurred. 


Data out of domain 
Results for mathematical parameters are 
not defined. 


Division by zero 
Division by zero was performed. 


Too long string 
The length of string literal exceeds 512 
characters. 


Invalid file pointer 
NULL pointer constant is specified as the 
file pointer value 


Invalid radix 
An invalid radix was specified. 


Number too long 
The specified number exceeds 17 digits. 


Exponent too large 
The specified exponent exceeds 3 digits. 


Normalized exponent too large 
The exponent exceeds three digits when 
the string literal is normalized to the IEEE 
standard decimal format. 


Overflow out of float 
A float-type decimal value is out of range 
(overflow). 


Underflow out of float 
A float-type decimal value is out of range 
(underflow). 
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Functions to Set Error Numbers 


atan, cos, sin, tan, cosh, sinh, tanh, 
exp, fabs, frexp, Idexp, modf, ceil, 
floor, strtol, atoi, fscanf, scanf, sscanf, 
atol 


acos, asin, atan2, log, log10, sqrt, 
fmod, pow 


divbs, divws, divls, divbu, divwu, divlu 


strtol, strtod, atof, atoi, atol 


fclose, fflush, freopen, setbuf, setvbuf, 
fprintf, fscanf, printf, scanf, sprintf, 
sscanf, vfprintf, vprintf, vsprintf, fgetc, 
fgets, fputc, fputs, ungetc, fread, 
fwrite, fseek, ftell, rewind, perror 
strtol, atol, atoi 

strtod, fscanf, scanf, sscanf, atof 


strtod, fscanf, scanf, sscanf, atof 


strtod, fscanf, sscanf, atof 


strtod, fscanf, scanf, sscanf, atof 


strtod, fscanf, scanf, sscanf, atof 


Table 4.1 


Error No. 


1250 
(EDBLO) 


1260 
(EDBLU) 


1270 
(ELDBLO) 


1280 
(ELDBLU) 


1300 
(NOTOPN) 


1302 
(EBADF) 


1304 
(ECSPEC) 


List of Standard Library Error Messages (cont) 


Error Message/Explanation 


Overflow out of double 


A double-type decimal value is out of range 


(overflow). 


Underflow out of double 


A double-type decimal value is out of range 


(underflow). 


Overflow out of long double 
A long double-type decimal value is out of 
range (overflow). 


Underflow out of long double 
A long double-type decimal value is out of 
range (underflow). 


File not open 
The file is not open. 


Bad file number 

An output function was issued for an input 
file, input file was issued for an output 
function. 


Error in format 
An erroneous format was specified for an 
input/output function using format. 
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Functions to Set Error Numbers 


strtod, fscanf, scanf, sscanf, atof 


strtod, fscanf, scanf, sscanf, atof 


fscanf, scanf, sscanf 


fscanf, scanf, sscanf 


fclose, fflush, setbuf, setvbuf, fprintf, 
fscanf, printf, scanf, sprintf, sscanf, 
vfprintf, vprintf, vsprintf, fgetc, fgets, 
fputc, fouts, gets, puts, ungetc, fread, 
fwrite, fseek, ftell, rewind, perror, 
freopen 

fprintf, fscanf, printf, scanf, sprintf, 
sscanf, vfprintf, vprintf, vsprintf, fgetc, 
fgets, fputc, fputs, gets, puts, ungetc, 
perror, fread, fwrite 


fprintf, fscanf, printf, scanf, sprintf, 
sscanf, vfprintf, vprintf, vsprintf, perror 
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Section 5 Inter-Module Optimizer 


5.1 Overview 


The inter-module optimizer is a software system that receives the multiple object programs from 
the compiler, optimizes them with consideration to relation between them, then invokes the 
linkage editor to link and edit them. The inter-module optimizer optimizes more than one object 
which has been impossible by conventional compilers. 


With the use of this optimizer, three types of load module formats below can be output. 


e ELF/DWARF format (object part in ELF and debugging information in DWARF) 
e SYSROF format (object part in SYSROF and debugging information in SYSROF) 
e SYSROF PLUS format (object part in SYSROF and debugging information in DWARF) 


Note: To format load modules in other than SYSROF, the inter-module optimizer must be 
invoked. 


To use the inter-module optimizer, software products below are necessary. 


e SuperH RISC engine C/C++ compiler (Ver.5.0) 
e H series linkage editor (Ver.6.0) 


Notes: 1. This inter-module optimizer optimizes object programs to files of which the goptimize 
option is specified at compilation, or object programs for which supplementary 
information files have been created. 

Object programs created without the specification of the goptimize option, object 
programs of SH series C compiler Ver.4.1 or before, and object programs of SH series 
C++ compiler Ver.1.1 or before can be mixed in the input files of the optimizer, but 
only object programs created with the goptimize option specified are optimized. 

2. The compiler automatically creates directory shiop under the object program output 
directory, to store supplementary information files under shiop. 


3. Since the optimizer invokes the linkage editor, the H series linkage editor is necessary. 
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Dk How to Invoke the Optimizer 
The format for the command line used to invoke the optimizer is as follows. 
optinksh [A<option>...] 


To execute the optimizer, use the related software and create the following files (related software 
names are parenthesized): 


e Object program (SuperH RISC engine C/C++ compiler) 
e Linkage editor subcommand file 


The basic operating method of the optimizer is described below using the sample program. 
e testl.c: C programs 

e testl.sub: subcommand file for optimizer 

5.2.1 Compiling Programs 


Compile testl.c. Be sure to specify the goptimize option. When the debug option is 
specified, debug information for source-level debugging can be output. 


she -goptimize -debug test1.c(RET) 


5.2.2 Specifying the Default Library 


Specify the standard library that is used during linking as a default library. For more information 
on the default library, refer to the H Series Linkage Editor, Librarian, and Object Converter User's 
Manual. 


e PC version (when DOS prompt is used): 
set HLNK_LIBRARY1=<standard library path>\shc.lib (RET) 
e UNIX version: 
setenv HLNK_LIBRARY1 <standard library directory>/shc.lib (RET) 


5.2.3 Executing the Optimizer 


Optimize testl.obj, and create the load module. Be sure to specify the linkage editor subcommand 
file. 


Example 1: Optimization and linkage of the object program 
optinksh -optimize -subcommand=test1l.sub (RET) 
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<testl.sub> 


input testl 


entry 


_main 


debug 


start P,C(200) ,D,B(08000) 


exit 


Description 


Specify the 
Specify the 
execution. 

Specify the 
Specify the 


input file name. 


function name that starts 


debug information output. 


start address of sections. 


Exit the processing. 


Refer to the H Series Linkage Editor, Librarian, and Object Converter User's Manual when 


creating a linkage editor subcommand file. 


Example 2: Specification of the contents of optimization 


The contents of optimization can be specified by a suboption of the optimize option. 


optinksh -optimize=speed -subcommand=test1.sub 


(RET) 


Example 3: Specification of the optimization option by the subcommand 


The optimizer option can be specified in the linkage editor subcommand file as a subcommand. 


optinksh -subcommand=test2.sub 


<test2.sub> 


optimize 
input 
entry 
execution. 
debug 
start P,C(200) ,D,B(08000) 


exit 


(RET) 


Specify the 
Specify the 


Specify the 


Specify the 
Specify the 


optimizer option. 
input file name. 


function name that starts 


debug information output. 


start address of sections. 


Exit the processing. 


5.2.4 Displaying the Command Input Format and Options 


Display the command input format and option list on the standard output display. 


optinksh (RET) 
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5.3 Options/Subcommands 
The option/subcommand format is as follows: 


Option: -<option> [=<parameter>[,<parameter>...]] 
Subcommand: <subcommand>A [<parameter>[,<parameter>...]] 


Table 5.1 lists the option/subcommand names, abbreviations, and defaults. Characters underlined 
indicate the minimum valid abbreviation. 


Note: The options and subcommands marked with * are supported by Ver. 5.1 or later. Ver 5.0 
supports the options and subcommands that are not marked with *. 


Table 5.1. Options 


Option/sub- 
Item command Parameter Default Specification 
Optimization optimize* string_unify optimize= Specifies optimization contents: 
contents | symbol_delete — string_unify, unify the constant/character 
| register symbol_delete, _ string, delete unreferred 
| same_code register, symbols, allocate the register, 
| branch same_code, unify common codes, optimize 
| speed branch the branch instruction, speed- 
| safe (or optimize) emphasized optimization 
(op=st, sy, r, b), safe 
optimization (op=st, r, b) 
nooptimize* — None Specifies optimization inhibition 
samesize* <size> samesize=1E Specifies the object size of the 
size: hexadecimal common code unification 
(optimize=same_code) 
Optimization symbol_ <symbol name> None Specifies the variable/function 
inhibition forbid* [,<symbol name that inhibits the 
name>...] optimization of unreferred 
symbol name: symbol deletion 
<variable name> | (optimize=symbol_delete) 
<function name> 
samecode_ <functionname> None Specifies the function name that 
forbid* [,<function avoids the optimization of 
name>...] common code unification 
(optimize=same_code) 


f = ELF/DWARF format 


Object format el 
specification 


sysrof SYSROF format 
sysrofplus SYSROF PLUS format 
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Table 5.1 Options (cont) 


Option/sub- 
Item command Parameter Default Specification 
Optimization information* — None Specifies display of the 
information optimized function name 
Sub-command sub- <file name> None Specifies the subcommand file 
file command for the linkage editor 


Notes: 1. For description rules and restrictions on the subcommand file, refer to the H Series 
Linkage Editor, Librarian, and Object Converter User's Manual. 


2. When the object format specification is omitted, sysrof is assumed. 


5.3.1 Specifying Optimization Contents 


(1) optimize Option/Subcommand 


Format: Option: -optimize [=<parameter>[,<parameter>...]] 
Subcommand: optimize [A<parameter>[,<parameter>...]] 
Parameter: string unify|symbol_ delete|register|same_code | 


branch | speed|safe 
Description: 


Executes inter-module optimization. By specifying parameters, the optimization contents can be 
specified. Multiple parameters can be specified. 


e No parameters: Executes all optimization. Has the same effect as the 
optimize=string unify, symbol delete, register, branch. 

e string_unify: Unifies equivalent constants and equivalent character strings for constants and 
character strings having the const attribute in modules. This optimization is executed only for 
the object program output from the compiler. The constants and character strings having the 
const attribute include variables with const declaration in the C program, the initial values of 
the character string data and variables for which extern const are declared in C++ program 
(class objects assigned to section D are excluded). 

e symbol_delete: Deletes variables and functions that have not been referred to. This 
optimization is executed only for the object program output from the compiler. To specify this 
optimization, specify the ent ry subcommand in the subcommand file for the linkage editor. 

e register: Analyzes function calls and deletes redundant register save/recovery codes. Can 
change register numbers depending on register usage before or after the call. This 
optimization is executed only for the object program output from the compiler. 


e same_code: Reduces code size by creating the subroutine of the same instruction sequence. 
This optimization is executed only for the object program output from the compiler. 
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e branch: Optimizes branch instruction size based on the program allocation information. This 
optimization applies to C/C++ object programs. When any other optimization item is 
executed, this optimization is executed regardless of your specifications. 


e speed: Executes optimization that does not cause a decrease in object speed, such as a 
replacement of the same instruction sequence with a subroutine. The opt imize=speed has 
the same effect as the optimize=string unify, symbol delete, register, 
branch. 


e safe: The variables with fixed absolute address and functions emphasizing speed must partially 
inhibit optimization. The opt imize=safe executes optimization that is not limited by the 
attribute of the variables and functions. The opt imize=safe has the same effect as the 
optimize=string unify, register, branch. 


Note: For the parameters of the opt imi ze option/subcommand, the logical OR of the specified 
parameters is effective. For instance, when optimize=speed, same_code is 
specified, optimize=string unify, symbol delete, register, 
branch, same_code is enabled. 


(2) nooptimize Option/Subcommand 


Format: Option: -nooptimize 
Subcommand: nooptimize 
Parameter: none 

Description: 


Executes only linking and editing according to the linkage editor command specified with the 
subcommand option without inter-module optimization, and generates the same load module as 
that generated when the linkage editor is directly invoked. 


(3) samesize Option/Subcommand 


Format: Option: -samesize=<parameter> 
Subcommand: samesizeA<parameter> 
Parameter: <value> 

Description: 


Specifies the size of the common code to be optimized for optimize=same_code. The size 
specified by this option indicates the number of bytes of the object program. When the 
optimize=same_ code option is not enabled, this option is ignored. 


e Value: Specified in hexadecimal. Executes a replacement of the common code in an 
instruction string greater than the specified size with a subroutine. When this option is 
omitted, samesize=1E is assumed. The specifiable range is from 8 to 7FFF. 
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5.3.2 Specifying Optimization Inhibition 


(1) symbol_forbid Option/Subcommand 


Format: Option: -symbol forbid=<parameter>[,<parameter>...] 
Subcommand: symbol forbidA<parameter>[,<parameter>...] 
Parameter: <symbol name> 

Description: 


Specifies the variable name and the function name in which unreferred symbols must not be 
deleted by optimization (opt imize=symbol delete). When the 
optimize=symbol delete option is not enabled, this option/subcommand is ignored. 


e Symbol name: For variable names and function names, "_" is added at the top of the 
definition name in the C program. Specify any variable names and function names in which 
unreferred symbols must not be deleted by optimization. Function names in C++ program are 
modified from definition names according to the encoding rules shown in Appendix H. 


(2) samecode_forbid Option/Subcommand 


Format: Option: -samecode_forbid=<parameter>[,<parameter>...] 
Subcommand: samecode_forbidA<parameter>[,<parameter>...] 
Parameter: <function name> 

Description: 


Specifies the function name in which the common code must not be unified by optimization 
(optimize=same_code). When the optimize=same_code option is not enabled, this 
option/subcommand is ignored. 


e Function name: For function names, "_" is added at the top of the definition name in the C 
program. Encoded function names are used in C++ programs. If it is required to know the 
function names encoded by the compiler, refer to the function names in the assembly source 
file or in the listing generate with the -code=asm or -lis option. Refer to appendix H, Encoding 
Rules. The common code unification can decrease code size; however, execution speed may be 
lowered. Specify the function name in which the common code must not be unified to increase 


speed by optimization. 


5.3.3 Object Format Specification 


(1) Option/Subcommand Specifying Object Format 


Format: Subcommand: elf 
sysrof 
sysrofplus 
Parameter: none 
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Description: 


Converts the file into the selected object format. 


5.3.4 Optimization Information 


(1) information Option/Subcommand 


Format: Option: -information 
Subcommand: information 
Parameter: none 

Description: 


Specifies display of the optimized function names. 


5.3.5 Subcommand File 


(1) subcommand Option 


Format: Option: -subcommand=<parameter> 
Parameter: <file name> 
Description: 


Specifies the subcommand file for the linkage editor. This optimizer automatically invokes the 
linkage editor and executes linking and editing after optimization. Therefore, this option cannot 
be omitted. 


File name: Specifies the subcommand file name for the linkage editor. The subcommand file 
name cannot include the "-" character. 


Notes: For more information on the subcommand and the subcommand file of the linkage editor, 
refer to the H Series Linkage Editor, Librarian, and Object Converter User's Manual. 
Create the subcommand file with the following items in mind: 


1. The optimizer subcommands can be specified in the subcommand file of the linkage 
editor using the subcommand option. However, an error occurs when the 
subcommand file which has the optimizer subcommands is specified in the 
subcommand option to the H series linkage editor. 


2. When the print subcommand is specified, the temporary subcommand file name 
created by the optimizer is output to the map list. The temporary subcommand file is 
deleted after the optimizer operation. 


3. Linkage editor subcommands delete, rename, and exchange cannot be used. 
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Section 6 Error Messages for Inter-Module Optimization 


6.1 Error Messages 
This section lists the error messages for each level of error. 
Error messages are classified into the following four levels according to their severity: 


Error level (1) Information 
(W) Warning 
(E) Error 
(F) Fatal 
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6.1.1 


Information-level Messages 


Error No. Message 


0010 


0020 


0030 


0040 


0050 


0060 


0070 


0080 


0200 


0210 


0220 


0230 


0240 


<unit name 1> IS REPLACED 
WITH <unit name 2> (<file name>) 


<external name 1> IS RENAMED 
TO <external name 2> 


<external name> IS DELETED 


DUPLICATION UNIT - (<unit 
name>) IN (<file name>) IS 
DELETED 


<external reference symbol> 
CANNOT BE DEFINED 


<external name>CANNOT BE 
RENAMED 


<external name> CANNOT BE 
DELETED 


<unit name> CANNOT BE 
REPLACED 


<optimize parameter> OPTIMIZE: 
<section name> SECTION IS 
CREATED 


<optimize parameter> OPTIMIZE: 
<unit name>.<symbol name> 
MOVED <section name> SECTION 


<optimize parameter> OPTIMIZE: 
<unit name>.<symbol name> IS 
CREATED 


<optimize parameter> OPTIMIZE: 
<unit name>.<symbol name> IS 
DELETED 


<unit name>.<symbol name> IS 
OPTIMIZED 
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Explanation 


<unit name 1> was replaced with <unit name 2> 
in <file name>. 


<external name 1> was changed to <external 
name 2>. 


<external name> was deleted. 


More than one <unit name> was found. The unit 
name in the <file name> was deleted. 


<external reference symbol> cannot be found and 
therefore cannot be forcibly defined. 


<external name> cannot be found and therefore 
cannot be modified. 


<external name> cannot be found and therefore 
cannot be deleted. 


<unit name> cannot be found and therefore 
cannot be replaced. 


Optimization was performed according to the 
parameter <optimize parameter>, and section 
<section name> was created. 


Optimization was performed according to 
parameter <optimize parameter>, and <unit 
name>.<symbol name> was moved to section 
<section name>. 


Optimization was performed according to 
parameter <optimize parameter>, and <unit 
name>.<symbol name> was created. 


Optimization was performed according to 
parameter <optimize parameter>, and <unit 
name>.<symbol name> was deleted. 


The <unit name>.<symbol name> was optimized. 
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6.1.2 


Warning-level Messages 


Error No. Message 


1010 


1020 


1040 


1050 


1060 


1070 


1080 


1090 


1110 


1130 


1140 


1150 


1160 


1170 


DUPLICATE 
OPTION/SUBCOMMAND 
(<option/subcommand name>) 


IDENTIFIER CHARACTER 
EXCEEDS 251 (<name>) 


DUPLICATE SYMBOL (<symbol 


name>) 


UNDEFINED EXTERNAL SYMBOL 


(<unit name>.<symbol name>) 


REDEFINED SYMBOL 
(<symbol name>) 


SECTION ATTRIBUTE MISMATCH 


(<section name>) 


RELOCATION SIZE OVERFLOW 


(<unit name>.<section name>- 
<offset value>) 


ENTRY POINT MULTIPLY 
DEFINED 


DUPLICATE SECTION NAME 
(<section name>) 


CONFLICTING DEVICE TYPE 


SECTION IS NOT IN SAME 
MEMORY AREA (<section 
name>:xxxx-yyyy) 


INACCESSIBLE ADDRESS 
RANGE (<section name>) 


INVALID cpu 
OPTION/SUBCOMMAND 


ADDRESS SPACE DUPLICATE 


Explanation 


The same option or subcommand is specified 
more than once. The last option or subcommand 
is valid. 


More than 251 characters are specified for a 
name (unit name, section name, or symbol 
name). Characters up to and including the 251st 
are valid. 


The same external symbol is defined more than 
once. The first definition is valid. 


An undefined external symbol is referred. 
External reference is invalid and zero is assumed 
as the value. 


A symbol that has been defined before is defined 
again with the DEFINE option or subcommand. 
The DEFINE is ignored. 


Sections having the same name but different 
attributes or boundary alignment values have 
been input. They are handled as different 
sections. 


The relocation result has exceeded the relocation 
size. 


More than one object module having the start 
address specification is specified. The first 
specification of the start address is valid. 


The same section name is specified with options 
and subcommands. The first specification is valid. 


An information file of a CPU different from the 
target CPU of the input object module is 
specified. 


A section cannot be allocated within one memory 
area, and addresses xxxx to yyyy are allocated to 
a different memory area. 


A section is allocated to an unusable area. 


Although the relocatable format is specified as the 
load module file type, the CPU option or 
subcommand is specified. 


Sections overlap each other. 
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Error No. Message 


1180 


1190 


1200 


1210 


1220 


1230 


1240 


1250 


1260 


1270 


1280 


1600 


1610 


1700 


1710 


INVALID UDF 
OPTION/SUBCOMMAND 


RELOCATION VALUE IS ODD 
(<unit name>.<section name> - 
<offset value>) 


START ADDRESS NOT 
SPECIFIED FOR SECTION 
(<section name>) 


CANNOT FIND SECTION 
(<section name>) 


TOO LONG SUBCOMMAND LINE 


TOO MANY DIRECTORY 
COMMANDS 


NO DEBUG INFORMATION 


CANNOT SET ENTRY POINT 


TOO LONG CHARACTER 


EXTERNAL SYMBOL 0(<section 
name>) 


ILLEGAL SYMBOL REFERENCE 


INVALID SYMBOL_FORBID 
OPTION 


INVALID SAMECODE_FORBID 
OPTION 


CANNOT FIND SYMBOL 
SPECIFIED SYMBOL_FORBID 
(<symbol name>) 

CANNOT FIND SYMBOL 
SPECIFIED SAMECODE_FORBID 
(<symbol name>) 
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Explanation 


Although the absolute format is specified for the 
output load module type, the NOUDF option or 
subcommanid is specified. NOUDF is ignored. 


The result of displacement relocation is an odd 
value. The lowest bit is rounded down. 


A section that has not been specified with the 
START option or subcommand is used. 


The specified section cannot be found. 


A directory name was replaced and the number of 
its characters has exceeded 511. Characters up to 
and including the 511th are valid. 


More than 16 directories are specified with the 
DIRECTORY subcommand. Directories up to and 
including the 16th are valid. 


The DEBUG or SDEBUG option or subcommand 
is specified for a file that has no debugging 
information. Specify the debug option when 
compiling or assembling a file. 


An external reference symbol for a constant is 
specified as the execution start address when the 
output load module is in relocatable format. 
Change the output load module to absolute 
format, or delete the entry point specification. 


The section specified with the FSYMBOL 
subcommand has symbols of more than 238 
characters. 


The section specified with the FSYMBOL 
subcommand has no externally defined symbols. 


A symbol is referenced between the sections 
allocated to the same address with the start 
subcommand. 


The SYMBOL_FORBID specification is invalid. 


The SAMECODE_FORBID specification is invalid. 


The symbol name specified with the 
SYMBOL_FORBID cannot be found. 


The symbol name specified with the 
SAMECODE_FORBID cannot be found. 
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Error No. Message Explanation 


1800 <optimize parameter> OPTIMIZE: As aresult of optimization performed according to 
SECTION OVERLAP parameter <optimize parameter>, the section size 


has increased and the section has overlapped the 
adjacent section. The optimization specification 
of <optimize parameter> is disabled. 


1810 DIFFERENT SYMBOL ASSIGNED The symbol name and register number assigned 
TO A GLOBAL REGISTER to the global register differ between files. 


AMONG FILES (<symbol 
name>:<register number>) 


1820 STACK ACCESS SIZE As a result of register optimization, the stack 
OVERFLOW access code has exceeded the limitation of the 
compiler. The register optimization is invalidated. 
1830 RELOCATION VALUE EXISTS IN The unsolved symbol for the BSR is included in 
BSR (<unit name>) the assembly program of <unit name>. <unit 


name> is outside the optimization range. 
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6.1.3 


Error-level Messages 


Error No. Message 


2010 
2020 


2030 
2040 


2070 


2080 


2100 
2110 
2120 
2130 


2140 


2170 


2190 


2200 


2210 


2220 


2600 


ILLEGAL SUBCOMMAND/OPTION 
SYNTAX ERROR 


TOO LONG SUBCOMMAND LINE 
ILLEGAL SUBCOMMAND 
SEQUENCE 


ILLEGAL SECTION NAME 
(<section name>) 


ILLEGAL SYMBOL NAME 
(<symbol name>) 


TOO MANY INPUT FILES 
CANNOT FIND FILE(<file name>) 
CANNOT FIND UNIT(<unit name>) 


CANNOT FIND MODULE 
(<module name>) 


DUPLICATE START ADDRESS 
SPECIFIED 


SUBCOMMAND COMMAND IN 
SUBCOMMAND FILE 


INVALID ADDRESS (<address>) 


TOO MANY ROM COMMANDS 


CANNOT CREATE ABSOLUTE 
MODULE (<module name>) 


DIVISION BY ZERO IN 
RELOCATABLE VALUE (<unit 
name>.<section name>.<offset 
value>) 


COMPILER SUPPLEMENTARY 
INFORMATION FILE MISMATCH 
(<file name>) 
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Explanation 
An illegal subcommand or option is specified. 


A subcommand or option is specified in an illegal 
syntax. 


A subcommand has more than 511 characters. 


Subcommands are specified in an illegal order. 
An illegal section name is specified. 
An illegal symbol name is specified. 


More than 256 files have been input. 
The specified file cannot be found. 
The specified unit cannot be found. 


The specified module cannot be found. 


The same start address is specified more than 
once. 


A SUBCOMMAND subcommand is specified in a 
subcommand file. 


The specified address is outside the CPU 
address range. 


More than 64 pairs of sections are specified with 
the ROM subcommand. 


An undefined external reference symbol was 
found. 


The input object file includes division by zero. 


The time a compiler supplementary file was 
created does not match the time the object file 
was created. 


HITACHI 


Error No. 
2610 


2730 


2740 


2750 


2760 


Message 


ILLEGAL DUPLICATE SYMBOL 
(<symbol name>) 


ILLEGAL SAMESIZE SPECIFIED 


CANNOT OPTIMIZE 
RELOCATABLE FILE 


NOT SPECIFIED ENTRY 
SUBCOMMAND 


<subcommand name> NOT 
SUPPORT 


Explanation 


The same external symbol is defined more than 
once. 


An incorrect size is specified as the same_code 
size. 


The relocatable format is specified as the output 
load module file type. 


Although the optimize=symbol_delete is 
specified, the entry subcommand is not specified. 


The optimizer does not support this 
subcommand. Output the relocatable file with the 
linkage editor, and execute optinksh. 
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6.1.4 


3020 


3050 
3060 


3080 


3090 


3110 


3120 


3140 


3230 


3270 


Rev. 


Fatal-level Messages 


Message Explanation 
ILLEGAL COMMAND PARAMETER 
Cc (<file name>) The file cannot be opened. 


CANNOT READ INPUT FILE The file cannot be read. 
name>) 


CANNOT WRITE OUTPUT FILE The file cannot be written to. 


ANNOT CLOSE FILE (<file name>) 


| (<file 

name>) external symbol name specified with the 
RENAME subcommand already exists. 

ILLEGAL RECORD FORMAT The specified file includes an illegal record, or 

name>) 

S) The addresses allocated to a section are outside 

(<section name>) 

A The specified address is outside the CPU 
address range. 

MEMORY OVERFLOW 


processing of the inter-module optimizer. 


ROGRAM ERROR (<nnn>) 
optimizer internal processing. 


Check the program error number (nnn) and 


| 
ALIGNMENT (<address>) boundary alignment value of the object module. 


ANNOT FIND SECTION 
(<section name>) 


Ss The section specified with the ROM command 
OPTION/SUBCOMMAND DOES cannot be found. 

NOT EXIST 

ILLEGAL START SECTION An attribute of the section specified with the 


START command is illegal. 


CANNOT READ 
(including the standard I/O device). 


YMBOL ADDRESS OVERFLOW 
(<symbol name>) CPU address range. 


, 09 190 of 


HITACHI 


3300 


3310 


3320 


3330 


3340 


3360 


3370 


3710 


3730 
3740 


3750 


Message 


ILLEGAL ROM SECTION 
name>) 


LLEGAL FILE FORMAT ( 
ABSOLUTE FILE) 


LLEGAL FILE FORMAT 


( 
VERSION) 


LLEGAL FILE FORMAT ( 
MISMATCH CPU TYPE) 


CANNOT CLOSE INTERNAL FILE 


CANNOT DELETE INTERNAL FILE 


CANNOT READ INTERNAL FILE 


TOO MANY UNITS 
TOO MANY SECTIONS 
CANNOT OPEN CPU 


ANNOT OPEN INTERNAL FILE 
CANNOT WRITE INTERNAL FILE 
Cc 

ANNOT EXECUTE (<load module 


ANNOT CREATE INTERNAL FILE 
INTERRUPT BY USER 


Explanation 


A section that has a size of zero, or has absolute 
in the ROM option or subcommand, or the 


do not match. 


file. 


each other. 


series. 


The internal file cannot be opened. The disk does 
not have sufficient space, or the disk has an error. 


not have sufficient space, or the disk has an error. 
Check the disk and re-execute the operation. 


The internal file cannot be deleted. The disk does 


Check the disk and re-execute the operation. 


The internal file cannot be output. The disk does 
not have sufficient space, or the disk has an error. 


not have sufficient space, or the disk has an error. 
Check the disk and re-execute the operation. 


More than 65,535 units have been specified. 
More than 65,535 sections have been specified. 


The CPU information file cannot be opened. 


The intermediate file cannot be opened. 


The intermediate file cannot be closed. 


optink 
Check that they have been correctly installed. 


The intermediate file cannot be created. 


standard I/O terminal and the processing has 
been interrupted. 
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Error No. Message Explanation 


3770 CANNOT ANALYZE OBJECT The object code cannot be analyzed. 
(<unit name>) Delete the .DATA directive from the program 
section. 
SYMBOLS (<unit name>) Divide the file or do not specify the GOPTIMIZE 
option when compiling the unit. 
3810 TOO MANY EXTERNAL More than 65,535 symbols are referenced in a 
REFERENCE SYMBOLS (<unit unit. 
name>) Divide the file or do not specify the GOPTIMIZE 
option when compiling the unit. 
3820 TOO MANY SECTIONS (<unit A unit includes more than 65,535 sections. 
name>) Divide the file or delete the GOPTIMIZE option 
when compiling the unit. 
3830 <optimize parameter> OPTIMIZE: As aresult of optimization performed according to 
SECTION OVERLAP parameter <optimize parameter>, the section size 


has increased and the section has overlapped the 
adjacent section. 
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Section 7 Standard Libraries 


Overview of Libraries 


The following sections describe the specifications of the library functions, which can be used as 
standard functions in C/C++ language. This section gives an overview of the library 
configuration, and describes the layout and the terms used in this library function description. For 
additional information, refer to section A.2, Library Function Description. 


(1) Library Types 


A library implements standard processing such as input/output and string manipulation in the 
form of C/C++-language functions. Libraries can be used by including standard include files 
for each unit of processing. 


Standard include files contain declarations for the corresponding libraries and definitions of the 
macro names necessary to use them. 


Table 7.1 shows the various library types and the corresponding standard include files. 


Table 7.1 


Library Type 
Program diagnostics 
Character handling 


Mathematics 


Non-local jumps 


Signal handling 


Variable arguments 


Input/output 


General utilities 


String handling 


Date and time 


Library Types and Corresponding Standard Include Files 


Description 
Outputs program diagnostic information. 
Handles and checks characters. 


Performs numerical calculations such as trigonometric 
functions. 


Supports transfer of control between functions. 


Generates conditions for interrupts, etc., that occur 
during program execution and records 

the processing to be carried out when such conditions 
occur. 


Supports access to variable arguments for functions 
with such arguments. 


Performs input/output handling. 


Performs C program standard processing such 
as storage area management. 


Performs string comparison, copying, etc. 


Performs time-related handling. 


Standard Include 
Files 


<assert.h> 
<ctype.h> 


<math.h> 


<setjmp.h> 


<signal.h> 


<stdarg.h> 


<stdio.h> 
<stdlib.h> 


<string.h> 


<time.h> 
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In addition to the above standard include files, standard include files consisting solely of macro 
name definitions, shown in table 7.2, are provided to improve programming efficiency. 


Standard Include Files Comprising Macro Name Definitions 


Standard Include File 
<stddef.h> Defines macro names shared by the standard 


<float.h> 
floating-point numbers. 


Defines various limit values relating to compiler internal processing. 


(2) 
The organization of the library part of this manual is described below. 


Library functions are categorized for each standard include file, and descriptions are given for 


names and function declarations defined in the standard include file (figure 7.1), followed by a 
description of each function (figure 7.2). 


description layout. 


No. <standard include file name> 
Summarizes the overall function of this standard include file. 


Definition Names: 
this standard include file. 


Category of the definition | scription for the definition name. 
wn names declared 
in this standard include The definition name 

categories are as follows. 


Definition name categories 
Means a macro name with no parameters. 
(2) Macro: 
(3) Function: Means a frequent 
implemented by functions. 
(4) Tag name: 
declaration. 


In addition, notes common to the functions declared in this standard are given. 
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No. Function name 


Function name. Whether the library is implemented as 
functions or as macros*. 
Descrip- | Function of the library function. 
tion 
Calling Libr: e data declaration required when using the library 
procedure | fun 


Para- Type of the | Meaning of the parameter. 
meters parameter. | parameter. 


Shows the type of the return value. 
hang Shows the return value when the library function ends normally. 
Shows the return value when the library function ends abnormally. 


The library function specifications are given in detail. 


Notes 
Notes on the use of the library function. 
Error Conditions 


Conditions for the occurrence of errors that cannot be determined from the return value in library 
function processing. 


If such an error occurs, the value defined in each compiler for the error type is set in errno**. (See 
the user's manual for implementation-defined values.) 


Figure 7.2 Layout of Function Description 


Notes: * See section (3) (c) for the difference between functions and macros. 


** errno is a variable that stores the error type if an error occurs during execution of a 
library function. See section 7.2, <stddef.h>, for details. 


(3) Terms Used in Library Function Descriptions 
(a) Stream input/output 


In data input/output, the input/output device was driven and OS functions called each time 
an input/output function was called for a single character, resulting in poor efficiency. 
Therefore, a storage area called a buffer is normally provided, and the data in the buffer is 
input or output at one time. 


From the viewpoint of the program, on the other hand, it is more convenient to call 
input/output functions for each character. 
Using the library functions, character-by-character input/output can be performed 


efficiently without awareness of the buffer status within the program by automatically 
performing buffer management. 
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The function that enables a program to be written considering the input/output as a single 
data stream, making it possible to implement data input/output efficiently without being 
aware of the detailed procedure, is called stream input/output. 


(b) FILE structure and file pointer 


The buffer, and other information, required for the stream input/output described in (a) are 
stored in a single structure, defined by the name FILE in the <stdio.h> standard include 
file. 

In stream input/output, all files are handled as having a FILE structure data structure. Files 
of this kind are called stream files. A pointer to this file structure is called a file pointer, 
and is used to specify an input/output file. 


The file pointer is defined as 

FILE *fp ; 
When a file is opened by the fopen function, etc., the file pointer is obtained. If the open 
processing fails, NULL is returned. Note that if a NULL pointer is specified in another 
stream input/output function, that function will end abnormally. When a file is opened, the 
file pointer value must be checked to see whether the open processing was successful. 


(c) Functions and macros 
There are two library function implementation methods: functions and macros. 


A function has the same interface as an ordinary user-written function, and is incorporated 
during linkage. A macro is defined using a #define statement in the standard include file 
relating to the function. 


The following points must be noted concerning macros: 


(i) Macros are expanded automatically by the preprocessor, and therefore a macro cannot 
be invalidated even if the user declares a function with the same name. 


(11) If an expression with a subsidiary operation as a macro parameter (assignment 
expression, increment, decrement) is specified, its result is undefined. 


Example: Macro definition of MACRO that obtains the absolute value of a parameter, 
as follows 


If the following definition is made: 

#define MACRO (a) (a) s= 0 ? (a) = = (a) 
then if 

X = MACRO (a++) 


is in the program, the macro will be expanded as follows: 
X = (a++) >= 0 ? (at+) : - (at+) 


a will be incremented twice, and the resultant value will be different from the absolute 
value of the initial value of a. 
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(d) EOF 
In functions such as getc, getchar, and fgetc, that input data from a file, EOF is the value 
returned at end-of-file. The name EOF is defined in the <stdio.h> standard include file. 
(e) NULL 
This is the value when a pointer is not pointing at anything. The name NULL is defined in 
the <stddef.h> standard include file. 
(f) Null characters 
The end of a character string in C is indicated by the characters \0. String parameters in 
library functions must also conform to this convention. The characters \0 indicating the 
end of a string are called null characters. 
(g) Return code 
With some library functions, a return value is used to determine the result (such as whether 
the specified processing succeeded or failed). In this case, the return value is referred to as 
the return code. 
(h) Text files and binary files 
Many systems have special file formats for storing data. To support this facility, library 
functions have two file formats: text files and binary files. 
(i) Text files 
A text file is used to store ordinary text, and consists of a collection of lines. In text file 
input, the new-line designator (\n) is input as a line separator. In output, output of the 
current line is terminated by outputting the new-line designator (\n). Text files are used 
for input/output of files that store standard text for each implementation. With text 
files, characters input or output by a library function do not necessarily correspond to a 
physical list of data in the file. Refer to the user's manual for the text file 
implementation method. 
(11) Binary files 
A binary file is configured as a row of byte data. Data input or output by a library 
function corresponds to a physical list of data in the file. 
(i) Standard input/output files 
Files that can be used as standard by input/output library functions without preparations 
such as file opening are called standard input/output files. Standard input/output files 
comprise the standard input file (stdin), standard output file (stdout), and standard error 
output file (stderr). 
(1) Standard input file (stdin) 
Standard file comprising input to a program. 
(11) Standard output file (stdout) 
Standard file comprising output from a program. 
(111) Standard error output file (stderr) 


Standard file for performing output of error messages, etc., from a program. 
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(j) Floating-point numbers 

Floating-point numbers are numbers represented by approximation to real-numbers. In aC 

source program, floating-point numbers are represented by decimal numbers, but inside the 

computer they are normally represented by binary numbers. 

In the case of binary numbers, the floating-point representation is as follows: 

2" X m (n: integer, m: binary fraction) 

Here, n is called the exponent of the floating-point number, and m is called the mantissa. 

The number of bits in n and m is normally fixed so that a floating-point number can be 

represented using a specific data size. 

Some terms relating to floating-point numbers are explained below. 

(i) Radix 
An integer value indicating the number of distinct digits in the number system used by 
a floating-point number (10 for decimal, 2 for binary, etc.). The radix is normally 2. 

(ii) Rounding 
Rounding is performed when an intermediate result of an operation of higher precision 
than a floating-point number is stored as a floating-point number. There is rounding 
up, rounding down, and half-adjust rounding (rounding up fractions over 1/2 and 
rounding down fractions under 1/2; or, with binary numbers, rounding down 0 and 
rounding up 1). 

(iii) Normalization 
When a floating-point number is represented in the form 2 x m, the same number can 
be represented in different ways. 
Example: The following two expressions represent the same value. 
25 x 1.0 (2) ((2) indicates a binary number) 
2° x 0.1 (2) 
Usually, a representation in which the leading digit is not 0 is used, in order to secure 
the number of valid digits. This is called a normalized floating-point number, and the 
operation that converts a floating-point number to this kind of representation is called 
normalization. 

(iv) Guard bit 
When saving an intermediate result of a floating-point operation, data one bit longer 
than the actual floating-point number is normally provided in order for rounding to be 
carried out. However, this alone does not permit an accurate result to be achieved in 
the event of digit dropping, etc. For this reason, the intermediate result is saved with 
an extra bit, called a guard bit. 

(k) File access mode 


This is string that indicates the kind of processing to be carried out on a file when it is 
opened. There are 12 different strings, as shown in table 7.3. 
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Table 7.3 File Access Modes 


Access Mode Meaning 


Open text file for reading 

Open text file for writing 

Open text file for addition 

Open binary file for reading 

Open binary file for writing 

Open binary file for addition 

Open text file for reading and updating 
Open text file for writing and updating 
Open text file for addition and updating 
Open binary file for reading and updating 
Open binary file for writing and updating 
Open binary file for addition and updating 


(1) Implementation definition 


Definitions differ for different compilers. Refer to section A.2, Library Function 
Description, for the definitions for each compiler. 


(m) Error indicator and end-of-file indicator 


The following two data items are held for each stream file: (1) an error indicator that 
indicates whether or not an error has occurred during file input/output, and (2) an end-of- 
file indicator that indicates whether or not the input file has ended. 

These data items can be referenced by the ferror function and the feof function, 
respectively. 

With some functions that handle stream files, error occurrence and end-of-file information 
cannot be obtained from the return value alone. The error indicator and end-of-file 
indicator are useful for checking the file status after execution of such functions. 


(n) File position indicator 


Stream files that can be read or written at any position within the file, such as disk files, 
have an associated data item called a file position indicator that indicates the current 
read/write position within the file. 


File position indicators are not used with stream files that do not permit the read/write 
position within the file to be changed, such as terminals. 
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(4) Notes on use of libraries 


(a) The contents of macros defined in a library differ for each compiler. 


When a library is used, the behavior is undefined if the contents of these macros are 


redefined. 


(b) With libraries, errors are not detected in all cases. The behavior is undefined if library 
functions are called in a form other than those shown in the descriptions in section 7.2 


onward. 


Tz <stddef.h> 


Overview 


Defines macro names used in common in the standard include file. 


Definition Names 


Definition Name Type 


ptrdiff_t Macro name 
size_t Macro name 
NULL Macro name 
errno Macro name 


Description 
Indicates the type of the result of subtracting two pointers. 


Indicates the type of the result of an operation using the 
sizeof operator. 


Indicates the value when a pointer is not pointing at anything. 
This value is such that the result of a comparison with 0 
using the equality operator (==) is true. 


If an error occurs during library function processing, the error 
code defined in the respective library is set in errno. By 
setting 0 in errno before calling a library function and 
checking the error code set in errno after the library function 
processing has ended, it is possible to check whether an 
error occurred during the library function processing. 


The above macro names are all implementation-defined. 
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Tee <assert.h> 
Overview 
Puts diagnostics into programs. 


Definition Names 


Definition Name Type Description 


assert Macro Puts diagnostics into programs. 


To invalidate the diagnostics defined by <assert.h>, define macro name NDEBUG with a #define 
statement (#define NDEBUG) before incorporating <assert.h>. 


The assert function is implemented as a macro. 


If an #undef statement is used for macro name assert, the result of subsequent assert calls will not 
be guaranteed. 


7.3.1 assert Macro 


Puts diagnostics into programs. 


#include <assert.h> 


Calling int expression; 
procedure 


assert (expression) ; 


Parameters ; ; : 
int type Expression to be evaluated 


Return value 


When expression is true, the assert macro terminates processing without returning a value. If 
expression is false, it outputs diagnostic information to the standard error file in the form defined 
by the compiler, and then calls the abort function. 


The diagnostic information includes the parameter program text, source file name, and source line 
numbers. 
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7.4 <ctype.h> 
Overview 
Performs type determination and conversion for characters. 


Definition Names 


Definition Name Type Description 

isalnum Function Tests for an alphabetic character or decimal digit. 
isalpha Function ‘Tests for an alphabetic character. 

iscntrl Function Tests for a control character. 

isdigit Function — Tests for a decimal digit. 

isgraph Function Tests for a printing character except space. 
islower Function Tests for a lower-case letter. 

isprint Function — Tests for a printing character, including space. 
ispunct Function Tests for a special character. 

isspace Function Tests for a white-space character. 

isupper Function __ Tests for an upper-case letter. 

isxdigit Function Tests for a hexadecimal digit. 

tolower Function Converts an upper-case letter to lower-case. 
toupper Function Converts a lower-case letter to upper-case. 


In the above functions, if the input parameter value is not within the range that can be represented 
by the unsigned char type and is not EOF, the operation of the function is undefined. Character 
types are listed in table 7.4. 
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Table 7.4 Character Types 


Character Type Description 

Upper-case letter Any of the following 26 characters 
‘A, ‘B, 'G. "Di ‘Ee. oe ‘C’, ‘H’, se is ‘K, g ‘M’, ‘N’, ‘oO, ‘P’, ‘Q’', ‘R’, coy 
i i ‘U’, i ‘Ww’, *; NG pra 


Lower-case letter Any of the following 26 characters 
‘a , , db, ‘Cc by 1 ‘e ’ hs ole ‘h’, ‘7, Ws ‘k’, ts ‘m’, ‘n, ‘oO, ‘p’, ‘q’, T ‘s’, t ‘u, 
‘Vv’, ‘Ww, x’, ‘y’, ‘Zz’ 

Alphabetic character Any upper-case or lower-case letter 

Decimal digit Any of the following 10 characters 
‘0’, ad lie 2. poe ‘4, poe ‘6, a ‘8’, ‘Q’ 

Printing character A character, including space (‘’) that is displayed on the screen 


(corresponding to ASCII codes 0x20 to 0x7E) 
Control character Any character except a printing character 


White-space character Any of the following 6 characters 
Space (‘’), form feed (‘\f), new-line (‘\n’), carriage return (‘\r’), horizontal 
tab (‘\t’), vertical tab (‘\v’) 


Hexadecimal digit Any of the following 22 characters 
10, Ven 2a Bs Be 01 0 Ce Sa 9: 
(A; (BY, °C, ‘DE’, 'F 
‘a’, ‘b’, ‘c’, ‘d’, ‘e’, ‘fF 


Special character Any printing character except space (‘’), an alphabetic character, or a 
decimal digit 
7.4.1 isalnum Function 


Tests for an alphabetic character or decimal digit. 


; #include <ctype.h> 
Calling int c, ret; 


procedure 
ret=isalnum(c 


ee 


Parameters 
a int type Character to be tested 


If character c is alphabetic or a decimal digit: Nonzero 
If character c is not alphabetic or a decimal digit: 0 


Return value} Normal 
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7.4.2 isalpha Function 


Function 


Tests for an alphabetic character. 


#include <ctype.h> 


Calling int c, ret; 
procedure 


ret=isalpha(c 


oe a 


Parameters 
an Sa eet int type Character to be tested 


Type 


If character c is alphabetic: Nonzero 


Return value} Normal If character c is not alphabetic: 0 


7.4.3 iscntrl Function 


Tests for a control character. 


#include <ctype.h> 
Calling int c, ret; 


procedure 
ret=iscntrl ( 


ee 


Parameters 
eam ge oe int type Character to be tested 


‘Type | 
Ret | N If character c is a control character: Nonzero 
Sour Valve) Norma If character c is not a control character: 0 


| Abnormal _| 
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7.4.4 isdigit Function 


Function 


Tests for a decimal digit. 


#include <ctype.h> 
Calling int c, ret; 
procedure 


ret=isdigit(c 


a 


Parameters 
a ae int type Character to be tested 


[Type 
Ret If character c is a decimal digit: Nonzero 
piu vane) Normal If character c is not a decimal digit: 0 


| Abnormal | 


7.4.5 isgraph Function 


Function 


Tests for any printing character except space (‘’). 


: #include <ctype.h> 
Calling int c, ret; 


procedure 
ret=isgraph (c) ; 


; [Ne [Name [ype [Weaning 
arameters 
peer int type Character to be tested 


Ret I If character c is a printing character except space: Nonzero 
Sut SeINe) Monti lf character c is not a printing character except space: 0 
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7.4.6 islower Function 


Function 


Description | Tests for a lower-case letter. 


#include <ctype.h> 
Calling int @, Zeb; 
procedure 


ret=islower ( 


re Nene [ge [arg 
Parameters 


i ee et int type Character to be tested 


[Type | 
Return value| N lf character c is a lower-case letter: Nonzero 
anne If character c is not a lower-case letter: 0 


| Abnormal _| 


7.4.7 isprint Function 


Tests for a printing character, including space (‘’). 


#include <ctype.h> 


Calling int c, ret; 


procedure 
ret=isprint (c) 


a 
Parameters 


ae ae ae el int type Character to be tested 


If character c is a printing character, including space: Nonzero 
If character c is not a printing character, including space: 0 


CS 


Return value} Normal 
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7.4.8 ispunct Function 


Tests for a special character. 


#include <ctype.h> 
Calling int c, ret; 
procedure 


ret=ispunct (c) ; 


[Ne [Name [Type [Meaning 
Parameters 
ee ee int type Character to be tested 


Type 


If character c is a special character: Nonzero 


Return value} Normal If character c is not a special character: 0 


Abnormal 


7.4.9 isspace Function 


Tests for a white-space character. 


#include <ctype.h> 
Calling int c, ret; 


procedure 
ret=isspace(c) ; 


: [Ne [Name [Type Weaning 
arameters 
i 8 a Daa int type Character to be tested 


Normal | If character c is a white-space character: Nonzero 


Return value) Normal If character c is not a white-space character: 0 
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7.4.10 isupper Function 


Function 


Tests for an upper-case letter. 


#include <ctype.h> 
Calling int c, ret; 
procedure 


ret=isupper (c) ; 


[Ne [Name [Type Meaning 
Parameters 


[Type | 
Ret | N If character c is an upper-case letter: Nonzero 
Sturn Valle) Moria} lf character c is not an upper-case letter: 0 


| Abnormal. | 


ie ~ int type Character to be tested 


7.4.11  isxdigit Function 


Tests for a hexadecimal digit. 


#include <ctype.h> 
Calling int ¢, Tet; 


rocedure 
P ret=isxdigit (c) ; 


[Ne [Name [type [Meaning 


Parameters 
Fe ae a ae int type Character to be tested 


[Type | 
Ret If character c is a hexadecimal digit: Nonzero 
Se VAIS | Niel If character c is not a hexadecimal digit: 0 


| Abnormal. | 
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7.4.12  tolower Function 


foower «id tion 
Description | Converts an upper-case letter to the corresponding lower-case letter. 


#include <ctype.h> 
Calling int c, ret; 
procedure 


ret=tolower(c) ; 


Parameters 
int type Character to be converted 


If character c is an upper-case letter: Lower-case letter corresponding 
to character c 
If character c is not an upper-case letter: Character c 


moma [= SSSCSCS~*S 


Return value} Normal 


7.4.13 toupper Function 


toupper Function 
Description | Converts a lower-case letter to the corresponding upper-case letter. 


#include <ctype.h> 
Calling int c, ret; 
procedure 


ret=toupper (c) ; 


ters 
ani 


Type int 
lf character c is a lower-case letter: Upper-case letter 
Return value| Normal corresponding to character c 
If character c is not a lower-case letter: Character c 
Abnormal 
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13 <float.h> 


Overview 


Defines various limits relating to the internal representation of floating-point numbers. 


Definition Names 


Definition Name 
FLT_RADIX 
FLT_ROUNDS 


FLT_GUARD 


FLT_NORMALIZE 


FLT_MAX 


DBL_MAX 


LDBL_MAX 


FLT_MIN 


DBL_MIN 


Type 
Macro name 


Macro name 


Macro name 


Macro name 


Macro name 


Macro name 


Macro name 


Macro name 


Macro name 
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Description 
Indicates the radix in exponent representation. 


Indicates whether or not the result of an add operation is 
rounded off. 


The meaning of this macro definition is as follows: 

(1) When result of add operation is rounded off: Positive 
value 

(2) When result of add operation is rounded down: 0 

(3) When nothing is specified: —1 


The rounding-off and rounding-down methods are 
implementation-defined. 


Indicates whether or not a guard bit is used in multiply 
operations. 


The meaning of this macro definition is as follows: 
(1) When guard bit is used: 1 
(2) When guard bit is not used: 0 


Indicates whether or not floating-point values are 
normalized. 


The meaning of this macro definition is as follows: 
(1) When normalized: 1 
(2) When not normalized: 0 


Indicates the maximum value that can be represented as a 
float type floating-point value. 


Indicates the maximum value that can be represented as a 
double type floating-point value. 


Indicates the maximum value that can be represented as a 
long double type floating-point value. 


Indicates the minimum positive value that can be 
represented as a float type floating-point value. 


Indicates the minimum positive value that can be 
represented as a double type floating-point value. 
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Definition Name 
LDBL_MIN 


FLT_MAX_EXP 


DBL_MAX_EXP 


LDBL_MAX_EXP 


FLT_MIN_EXP 


DBL_MIN_EXP 


LDBL_MIN_EXP 


FLT_MAX_10_EXP 


DBL_MAX_10_EXP 


LDBL_MAX_10_EXP 


FLT_MIN_10_EXP 


DBL_MIN_10_EXP 


LDBL_MIN_10_EXP 


FLT_DIG 


DBL_DIG 


LDBL_DIG 


FLT_MANT_DIG 


Type 
Macro name 


Macro name 


Macro name 


Macro name 


Macro name 


Macro name 


Macro name 


Macro name 


Macro name 


Macro name 


Macro name 


Macro name 


Macro name 


Macro name 


Macro name 


Macro name 


Macro name 


Description 


Indicates the minimum positive value that can be 
represented as a long double type floating-point value. 


Indicates the power-of-radix maximum value that can be 
represented as a float type floating-point value. 


Indicates the power-of-radix maximum value that can be 
represented as a double type floating-point value. 


Indicates the power-of-radix maximum value that can be 
represented as a long double type floating-point value. 


Indicates the power-of-radix minimum value of a floating- 
point value that can be represented as a float type positive 
value. 


Indicates the power-of-radix minimum value of a floating- 
point value that can be represented as a double type 
positive value. 


Indicates the power-of-radix minimum value of a floating- 
point value that can be represented as a long double type 
positive value. 


Indicates the power-of-10 maximum value that can be 
represented as a float floating-point value. 


Indicates the power-of-10 maximum value that can be 
represented as a double floating-point value. 


Indicates the power-of-10 maximum value that can be 
represented as a long double floating-point value. 


Indicates the power-of-10 minimum value of a floating- 
point value that can be represented as a float positive 
value. 


Indicates the power-of-10 minimum value of a floating- 
point value that can be represented as a double positive 
value. 


Indicates the power-of-10 minimum value of a floating- 
point value that can be represented as a long double 
positive value. 


Indicates the maximum number of digits in float floating- 
point value decimal-precision. 


Indicates the maximum number of digits in double floating- 
point value decimal-precision. 


Indicates the maximum number of digits in long double 
floating-point value decimal-precision. 


Indicates the maximum number of mantissa digits when a 
float floating-point value is represented adjusted to the 
radix. 
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Definition Name 
DBL_MANT_DIG 


LDBL_MANT_DIG 


FLT_EXP_DIG 


DBL_EXP_DIG 


LDBL_EXP_DIG 


FLT_POS_EPS 


DBL_POS_EPS 


LDBL_POS_EPS 


FLT_NEG_EPS 


DBL_NEG_EPS 


LDBL_NEG_EPS 


FLT_POS_EPS_EXP 


Type 
Macro name 


Macro name 


Macro name 


Macro name 


Macro name 


Description 


Indicates the maximum number of mantissa digits when a 
double floating-point value is represented adjusted to the 
radix. 


Indicates the maximum number of mantissa digits when a 
long double floating-point value is represented adjusted to 
the radix. 


Indicates the maximum number of exponent digits when a 
float floating-point value is represented adjusted to the 
radix. 


Indicates the maximum number of exponent digits when a 
double floating-point value is represented adjusted to the 
radix. 


Indicates the maximum number of exponent digits when a 
long double floating-point value is represented adjusted to 
the radix. 


Macro name 


Macro name 


Indicates the minimum floating-point value x for which 
1.0 + x #1.0 in float type. 


Indicates the minimum floating-point value x for which 
1.0 + x # 1.0 in double type. 


Macro name 


Macro name 


Macro name 


Macro name 


Macro name 


DBL_POS_EPS_EXP Macro name 


LDBL_POS_EPS_EXP Macro name 


FLT_NEG_EPS_ EXP Macro name 


DBL_NEG_EPS_EXP Macro name 


LDBL_NEG_EPS_EXP Macro name 


Indicates the minimum floating-point value x for which 
1.0 + x # 1.0 in long double type. 


Indicates the minimum floating-point value x for which 
1.0 —x # 1.0 in float type. 


Indicates the minimum floating-point value x for which 
1.0 —x # 1.0 in double type. 


Indicates the minimum floating-point value x for which 
1.0 — x #1.0 in long double type. 


Indicates the minimum integer n for which 1.0 + (radix)" # 
1.0 in float type. 


Indicates the minimum integer n for which 1.0 + (radix)" # 
1.0 in double type. 


Indicates the minimum integer n for which 1.0 + (radix)" # 
1.0 in long double type. 


Indicates the minimum integer n for which 1.0 — (radix)" # 
1.0 in float type. 


Indicates the minimum integer n for which 1.0 — (radix)" # 
1.0 in double type. 


Indicates the minimum integer n for which 1.0 — (radix)" 4 
1.0 in long double type. 


The above macro names are all implementation-defined. 


Rev. 1.0, 09/98, page 212 of 476 


HITACHI 


7.6 <limits.h> 


Overview 


Defines various limits relating to the internal representation of integer type data. 


Definition Names 


Definition Name 


CHAR_BIT 
CHAR_MAX 


CHAR_MIN 


SCHAR_MAX 


SCHAR_MIN 


UCHAR_MAX 


SHRT_MAX 


SHRT_MIN 


USHRT_MAX 


INT_MAX 


INT_MIN 


UINT_MAX 


LONG_MAX 


LONG_MIN 


ULONG_MAX 


Type 

Macro name 
Macro name 
Macro name 
Macro name 
Macro name 
Macro name 
Macro name 
Macro name 
Macro name 
Macro name 
Macro name 
Macro name 
Macro name 


Macro name 


Macro name 


Description 
Indicates the number of bits of which char type is composed. 


Indicates the maximum value that a char type variable can 
have as a value. 


Indicates the minimum value that a char type variable can 
have as a value. 


Indicates the maximum value that a signed char type variable 
can have as a value. 


Indicates the minimum value that a signed char type variable 
can have as a value. 


Indicates the maximum value that an unsigned char type 
variable can have as a value. 


Indicates the maximum value that a short int type variable 
can have as a value. 


Indicates the minimum value that a short int type variable can 
have as a value. 


Indicates the maximum value that an unsigned short int type 
variable can have as a value. 


Indicates the maximum value that an int type variable can 
have as a value. 


Indicates the minimum value that an int type variable can 
have as a value. 


Indicates the maximum value that an unsigned int type 
variable can have as a value. 


Indicates the maximum value that a long type variable can 
have as a value. 


Indicates the minimum value that a long type variable can 
have as a value. 


Indicates the maximum value that an unsigned long type 
variable can have as a value. 


The above macro names are all implementation-defined. 
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vj <math.h> 


Overview 


Performs various mathematical operations. 


Definition Names 


Definition Name 
EDOM 


ERANGE 


HUGE_VAL 


acos 
asin 
atan 


atan2 


cos 
sin 
tan 
cosh 
sinh 
tanh 


exp 


frexp 


Idexp 


log 
logi0 


Type 
Macro name 


Macro name 


Macro name 


Function 
Function 
Function 


Function 


Function 
Function 
Function 
Function 
Function 
Function 


Function 


Function 


Function 
Function 


Function 
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Description 


Indicates the value to be set in errno if the value of an 
parameter input to a function is outside the range of values 
defined in the function. 


Indicates the value to be set in errno if the result of a function 
cannot be represented as a double value, or if overflow or 
underflow occurs. 


Indicates the value to be returned for the function return 
value if the result of a function overflows. 


Computes the arc cosine of a floating-point number. 
Computes the arc sine of a floating-point number. 
Computes the arc tangent of a floating-point number. 


Computes the arc tangent of the result of a division of two 
floating-point numbers. 


Computes the cosine of a floating-point radian value. 
Computes the sine of a floating-point radian value. 
Computes the tangent of a floating-point radian value. 
Computes the hyperbolic cosine of a floating-point number. 
Computes the hyperbolic sine of a floating-point number. 
Computes the hyperbolic tangent of a floating-point number. 


Computes the exponential function of a floating-point 
number. 


Breaks a floating-point number into a [0.5, 1.0) value and a 
power of 2. 


Multiplies a floating-point number by a power of 2. 
Computes the natural logarithm of a floating-point number. 


Computes the base-ten logarithm of a floating-point number. 


HITACHI 


Definition Name Type Description 


modf Function Breaks a floating-point number into integral and fractional 
parts. 

pow Function Computes a floating-point number raised to a power. 

sqrt Function Computes the nonnegative square root of a floating-point 
number. 

ceil Function Returns the smallest integral value not less than the given 
floating-point number. 

fabs Function Computes the absolute value of a floating-point number. 

floor Function Returns the largest integral value not greater than the given 


floating-point number. 


fmod Function Computes the floating-point remainder of division of two 
floating-point numbers. 


The above macro names are all implementation-defined. 
Operation in the event of an error is described below. 


(1) Domain error 


A domain error occurs if the value of a parameter input to a function is outside the domain 
over which the mathematical function is defined. In this case, the value of EDOM is set in 
erro. The function return value depends on the compiler; see the user's manual for details. 


(2) Range error 


A range error occurs if the result of a function cannot be represented as a double value. In this 
case, the value of ERANGE is set in errno. If the result overflows, the function returns the 
value of HUGE_VAL, with the same sign as the correct value of the function. If the result 
underflows, 0 is returned as the return value. 


Notes 


(1) If there is a possibility of a domain error resulting from a <math.h> function call, it is 
dangerous to use the resultant value directly. The value of errno should always be checked 
before using the result in such cases. 


Rev. 1.0, 09/98, page 215 of 476 
HITACHI 


Example: 


H=ASIinf( al ; 


LE (eerro ==EDoHd 


Prince [("eerorin")  ; 


eli 


mn of Ww ho oe 


Peintt ("result is : *din", H); 


In line 1, the arc sine value is found using the asin function. If the value of parameter a is 
outside the domain of the asin function [-1.0, 1.0], the EDOM value is set in errno. Line 2 
determines whether a domain error has occurred. If a domain error has occurred, error is 
output in line 3. If there is no domain error, the arc sine value is output in line 4. 


(2) Whether or not a range error occurs depends on the floating-point number internal 
representation format determined by the compiler. For example, if an internal representation 
format that allows infinity to be represented as a value is used, <math.h> library functions can 
be implemented without causing range errors. Refer to section A.2, Library Function 
Description, for details. 
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7.7.1 acos Function 


Function 
Computes the arc cosine of a floating-point number. 


#include <math.h> 


Calling double d, ret; 
procedure 


ret=acos (qd) ; 


Parameters 


1 double type Floating-point number for which 
arc cosine is to be found 
Return value Arc cosine of d 


In case of domain error: Result depends on the compiler. 


The acos function returns the arc cosine in the range (0, 1) radians. 
Error Conditions 


A domain error occurs for a value of d not in the range (—1.0, +1.0). 


Tolet asin Function 


Computes the arc sine of a floating-point number. 


#include <math.h> 


Calling double d, ret; 
procedure 


ret=asin(dqd); 


pee 
arc sine is to be found 
double 
Return value Arc sine of d 


In case of domain error: Result depends on the compiler. 


The asin function returns the arc sine in the range (—1/2, +7/2) radians. 


Error Conditions 


A domain error occurs for a value of d not in the range (—1.0, +1.0). 
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7.7.3 atan Function 


Computes the arc tangent of a floating-point number. 


#include <math.h> 


Calling double d, ret; 
procedure 


ret=atan(d); 


Parameters 


1 double type Floating-point number for which 
arc tangent is to be found 


Return value Arc tangent of d 


The atan function returns the arc tangent in the range (—1/2, +7/2) radians. 


7.7.4 atan2 Function 


Computes the arc tangent of the result of division between two floating-point 
numbers. 


#include <math.h> 
double x, y, ret; 


ret=atan2(y, x); 


Type double 


Calling 
procedure 


Return value| Normal Arc tangent value when y is divided by x 


The atan2 function returns the arc tangent in the range (—1, +7) radians. The meaning of the atan2 
function is illustrated in figure 7.3. As shown in the figure, the result of the atan2 function is the 
angle between a straight line passing through the origin and point (x, y), and the X-axis. 


In case of domain error: Result depends on the compiler. 


If y = 0.0 and x is negative, the result is t. If x = 0.0, the result is +7/2, according to whether y is 
positive or negative. 
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Figure 7.3 Meaning of atan2 Function 
Error Conditions 


A domain error occurs if the values of both x and y are 0.0. 


7.7.5 cos Function 


Computes the cosine of a floating-point radian value. 


#include <math.h> 


Calling double d, ret; 


procedure 
ret=cos (qd); 


Parameters 


double type Radian value for which cosine 
is to be found 


Return value Cosine of d 
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7.7.6 sin Function 


Computes the sine of a floating-point radian value. 


#include <math.h> 


Calling double d, ret; 
procedure 


ret=sin ( 


Parameters double type Radian tenn for which sine is 
to be found 


[Type | [Type _| double 


Return value Sine of d 


Welel tan Function 


Function 


Computes the tangent of a floating-point radian value. 


#include <math.h> 


Calling double d, ret; 


procedure 
ret=tan ( 


shave [eng 
Parameters 


double type Radian value for which tangent 
is to be found 


Return value Tangent of d 
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7.7.8 cosh Function 


Computes the hyperbolic cosine of a floating-point number. 


#include <math.h> 


Calling double d, ret; 
procedure 


ret=cosh(d); 


Parameters 1 double type Floating-point number for which 
hyperbolic cosine is to be found 


Return value Hyperbolic cosine of d 


7.7.9 sinh Function 


sinh Function 


Computes the hyperbolic sine of a floating-point number. 


#include <math.h>s 


Calling double d, ret; 


procedure 
ret=sinh(d); 


Parameters 1 double type Floating-point number for which 
hyperbolic sine is to be found 


Type double 
Return value Hyperbolic sine of d 
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7.7.10 tanh Function 


Function 


Computes the hyperbolic tangent of a floating-point number. 


#include <math.h> 


Calling double d, ret; 
procedure 


ret=tanh ( 


a 
Parameters 


double type Floating-point number for which 
hyperbolic tangent is to be found 
Return value Hyperbolic tangent of d 
| Abnormal_| 


7.711 exp Function 


Function 
Description | Computes the exponential function of a floating-point number. 


#include <math.h> 


Calling double d, ret; 


procedure 
ret=exp (d) ; 


i 
Parameters 


double type Floating-point number for which 
exponential function is to be 
found 


[Type [Type | double 


Return value Exponential value of d 
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7.712  frexp Function 


Description | Breaks a floating-point number into a [0.5, 1.0) value and a power of 2. 


#include <math.h> 
double ret, value; 
int *e; 


Calling 
procedure 


ret=frexp (value, e); 


a 


value double type Floating-point number to be 
Parameters broken into a [0.5, 1.0) value 
and a power of 2 


Pointer indicating | Pointer to storage area that 
int type holds power-of-2 value 


[Type | double 
If value is 0.0: 0.0 
Return value| Normal If value is not 0.0: Value of ret defined by 
= ret * 2° = value 
| Abnormal. 


The frexp function breaks value into a [0.5, 1.0) value and a power of 2. It stores the resultant 
power-of-2 value in the area pointed to by e. 


The frexp function returns the return value ret in the range [0.5, 1.0) or as 0.0. 


If value is 0.0, the contents of the int storage area pointed to by e and the value of ret are both 0.0. 
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7.7.13 \dexp Function 


Function 


Multiplies a floating-point number by a power of 2. 


#include <math.h> 
double ret, e; 


Calling Fs 
int < 


procedure 
ret=ldexp(e, £); 


1 double type Floating-point number to be 
Parameters multiplied by a power of 2 


Return value Result of e * 2' operation 


7.7.14 log Function 


Function 


Computes the natural logarithm of a floating-point number. 


#include <math.h> 
double d, ret; 


Calling 
procedure 


ret=log(d) ; 


ie GD ell = — 
natural logarithm is to be found 
double 
Return value Natural logarithm of d 


In case of domain error: Result depends on the compiler. 


Error Conditions 


A domain error occurs if d is negative. 


A range error occurs if d is 0.0. 
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7.7.15 log10 Function 


Function 


Computes the base-ten logarithm of a floating-point number. 


#include <math.h> 


Calling double d, ret; 
procedure 


ret=1log10 (qd); 


Parameters 


1 double type Floating-point number for which 
base-ten logarithm is to be found 
Return value Base-ten logarithm of d 


In case of domain error: Result depends on the compiler. 


Error Conditions 
A domain error occurs if d is negative. 


A range error occurs if d is 0.0. 


7.7.16  modf Function 


Description | Breaks a floating-point number into integral and fractional parts. 


; #include <math.h> 
Calling double a, *b, ret; 


procedure 
ret=modf(a, b); 


1 double type Floating-point number to be 
p t broken into integral and 
arneselS fractional parts 
2 Pointer indicating | Pointer indicating storage area 
double type that stores integral part 


Return value Fractional part of a 
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7.7.17 pow Function 


Function 


Computes a floating-point number raised to a power. 


#include <math.h> 


Calling double x, y, ret; 
procedure 


ret=pow(x, y); 


Parameters double type Value to be raised to a power 


Return value Value of x raised to the power y 
In case of domain error: Result depends on the compiler. 


Error Conditions 


A domain error occurs if x is 0.0 and y is 0.0 or less, or when x is negative and y is not an integer. 


7.7.18 sqrt Function 


Description | Computes the nonnegative square root of a floating-point number. 


. #include <math.h> 
Calling double d, ret; 


rocedure 
P ret=sqrt (d) ; 


Parameters 


1 double type __| Floating-point number for which 
nonnegative square root is to 
be found 


Type double 


Return value Nonnegative square root of d 
In case of domain error: Result depends on the compiler. 


Error Conditions 


A domain error occurs if d is negative. 
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7.7.19 ceil Function 


Function 
Description | Returns the smallest integral value not less than the given floating-point number. 


#include <math.h> 


Calling double d, ret; 
procedure 


ret=ceil(d); 


Parameters 


1 double type Floating-point number for which 
smallest integral value not less 
than that number is to be found 


Return value Smallest integral value not less than d 


The ceil function returns the smallest integral value not less than d, expressed as a double. 
Therefore, if d is negative, the value after truncation of the fractional part is returned. 


7.7.20 fabs Function 


Computes the absolute value of a floating-point number. 


#include <math.h> 
Calling double d, ret; 
procedure 
ret=fabs(d); 


Parameters 1 double type Floating-point number for which 
absolute value is to be found 


Type double 
Return value Absolute value of d 


Rev. 1.0, 09/98, page 227 of 476 
HITACHI 


7.7.21 floor Function 


Returns the largest integral value not greater than the given floating-point number. 


#include <math.h> 


Calling double d, ret; 
procedure 


ret=floor ( 


a 
Parameters 


double type Floating-point number for which 
largest integral value not greater 
than that number is to be found 


Type [Type | double 
Return value Largest integral value not greater than d 


The floor function returns the largest integral value not greater than d, expressed as a double. 
Therefore, if d is negative, the value after rounding-up of the fractional part is returned. 


7.7.22 fmod Function 


Computes the floating-point remainder of division of two floating-point numbers. 


#include <math.h> 


Calling double x, y, ret; 


procedure ret=fmod (x 


ae 


double 


Normal When y is 0.0: x 
Return value When ey is not 0.0: Remainder of division of x by y 


| Abnormal | 


In the fmod function, the relationship between parameters x and y and return value ret is as 
follows: 


x = y *1+ ret (where i is an integer) 
The sign of return value ret is the same as the sign of x. 
If the quotient of x/y cannot be expressed, the value of the result is undefined. 
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7.8 <setjmp.h> 
Overview 
Supports transfer of control between functions. 


Definition Names 


Definition Name Type Description 

jmp_buf Macro name _ Indicates the type name corresponding to a storage area for 
storing information that enables transfer of control between 
functions. 

setimp Function Saves the calling environment defined by jmp_buf of the 


currently executing function in the specified storage area. 


longjmp Function Restores the function calling environment saved by the 
setjmp function, and transfers control to the program location 
at which the setjmp function was called. 


The above macro names are implementation-defined. 


The setjmp function saves the calling environment of the current function. The location in the 
program that called the setjmp function can subsequently be returned to by calling the longjmp 
function. An example of how transfer of control between functions is supported using the setjmp 
and longjmp functions is shown below. 
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Example 


#incliwile <stdio.hs 
#inclivle csetjmp. ho 
jmp_but error; 

maint } 


{ 


LE (set jmp fer) !=0) 7 
pELMeE ("return from Longgmpin') ; 
SeHLt(O); 


WOW HU Aw he 


I; 


peinteEl "subroutine is wunnirey'n') ; 
Lory terol); 


Explanation 


The setjmp function is called in line 8. At this time, the environment in which the setjmp function 
was called is saved in jmp_buf type variable env. The return value in this case is 0, and therefore 
function sub is called next. 


The environment saved in variable env is restored by the longjmp function called within function 
sub. As a result, the program behaves just as if a return had been made from the setjmp function 
in line 8. However, the return value at this time is the value (1) specified by the second parameter 
of the longjmp function. As a result, execution proceeds from line 9. 
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7.8.1 setjmp Function 


Function 


Description | Saves the calling environment of the currently executing function in the 
specified storage area. 


#include <setjmp.h> 
int ret; 
jmp buf env; 


Calling 
procedure 
ret=setjmp (env) ; 


Parameters 1 env jmp_buf type Pointer to storage area in which 
calling environment is to be saved 
fuel When setjmp function is called: 0 
Return value| Normal On return from longjmp function: Nonzero 


The calling environment saved by the setjmp function is used by the longjmp function. The return 
value is 0 when the function is called as the setjmp function, but the return value on return from 
the longjmp function is the value of the second parameter specified by the longjmp function. 


Note 


If the setjmp function is called from a complex expression, part of the current calling environment, 
such as the intermediate result of expression evaluation, may be lost. The setjmp function should 
only used in the form of a comparison between the result of the setjmp function and a constant 
expression, and should not be called within a complex expression. 
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7.8.2 longjmp Function 


D aT Restores the function calling environment saved by the setjmp function, and 
escription | transfers control to the program location at which the setjmp function was called. 


#include <setjmp.h> 
int ret; 
jmp buf env; 


Calling 
procedure 
longjmp(env, ret) 


a 
jmp_buf type Pointer to storage area in which 
int type Return code to setjmp function 


Type void 


Return value| Normal 
Abnormal 


The longjmp function restores from the storage area specified by env the function calling 
environment saved by the most recent invocation of the setjmp function in the same program, and 
transfers control to the program location at which that setjmp function was called. The value of 
longjmp function parameter ret is returned as the setjmp function return value. However, if ret is 
0, the value | is returned to the setjmp function as a return value. 


Note 


If the setjmp function has not been called, or if the function that called the setjmp function has 
already executed a return statement, the operation of the longjmp function is undefined. 
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Pe <signal.h> 


Overview 


Generates conditions for interrupts, etc., that occur during program execution, and registers the 
processing to be carried out when such conditions occur. 


Definition Names 


Definition Name 
SIGABRT 


SIGFPE 


SIGILL 


SIGINT 


SIGSEGV 


SIGTERM 


SIG_IGN 


SIG_DFL 


SIG_ERR 


signal 


raise 


Type 
Macro name 


Macro name 


Macro name 


Macro name 


Macro name 


Macro name 


Macro name 


Macro name 


Macro name 


Function 


Function 


Description 


Shows the signal number corresponding to an irrecoverable 
error condition. 


Shows the signal number corresponding to an erroneous 
arithmetic operation such as divided by zero or an operation 
resulting in overflow. 


Shows the signal number corresponding to detection of an 
invalid function code. 


Shows the signal number indicating receipt of an interrupt 
signal consciously sent by the user from a terminal, etc., to 
the program. 


Shows the signal number indicating invalid access to a data 
storage area. 


Shows the signal number indicating a termination request 
sent to the program. 


Shows the signal number corresponding to processing in 
which a signal is ignored if generated. 


Shows the signal number corresponding to processing in 
which predetermined implementation-defined processing is 
performed when a signal is generated. 


Shows the macro name for indicating that an error has 
occurred in the signal function. 


Registers what kind of processing is to be carried out when a 
signal is generated. 


Generates a signal in the executing program. 


Conditions such as interrupts that may occur during program execution are called signals. The 
following macro names are defined, corresponding to each of the signal types: 


SIGABRT, SIGFPE, SIGILL, SIGINT, SIGSEGV, SIGTERM 


An integer that is called a signal number corresponds to each of these. The above macro names 
are all implementation-defined. 
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The processing to be carried out when an interrupt is generated can be registered in the signal 
function. When registering this information, execution of standard processing can be specified by 
setting the value defined by SIG_IGN or SIG_DFL. 


An example of a program using the signal function is shown below. 


Example 


#include <stdlic. ko 
#incluce csigmal hs 


wold interrupt [int sig) 
{ 

peintel "interrupt in") ; 
} 


1 
2 
3 
4 
a 
6 
? 
a 
a 


maLnt } 


wub1l{ }; 

aigqral(SsDGDHT, S0DG_IGH) ; 
peintf("intesrupt disbledin") ; 
sub2t }; 

sigma l (SIGINT, interrupt) ; 
sub3{ }; 

EAL so (SIGHT) ; 


Explanation 


In function sub1 called in line 11, standard processing is performed by the system in response to 
the generation of an interrupt or other condition. 


In line 12, signal ignore processing (SIG_IGN) is registered by the signal function for an interrupt 
from a terminal, etc., (SIGINT). As a result, interrupts from a terminal, etc., are ignored in 
function sub2 called in line 14. 


In line 15, function interrupt defined in line 4 is registered for SIGINT. As a result, function 
interrupt processing is performed for interrupts from a terminal, etc., in function sub3 called in 
line 16. 


The raise function in line 17 generates an interrupt condition from a terminal, etc., in the program. 
As a result, function interrupt processing is carried out. 
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pa | signal Function 


Function 


Registers processing to be carried out when various signals are generated. 


#include <signal.h> 
. int sig; 
Calling void(*func) (int) ; 
procedure | ¥oi3q(*ret) (int); 


ret=signal(sig, func); 


[Ne [Nave [Tipe CMearng 


— ee E 
Pointer to function with a} Pointer to function to be executed 
void type return value when signal is generated 
Pointer to function with a void type return value 
Pointer to function in which registering for same signal was 
Return value} Normal performed previously 


SIG_ERR value 


Registers the processing specified by func for the signal number specified by sig. In addition to 
the specification of an ordinary function, the SIG_DFL or SIG_IGN macro name can also be 
specified for func. 


(1) When func is SIG_DFL 


When the specified signal is generated, the predetermined implementation-defined processing 
is executed. 


(2) When func is SIG_IGN 


Generation of the specified signal is ignored. 


(3) When func is an ordinary function 


When the specified signal is generated, the predetermined implementation-defined processing 
is first executed, then the function registered here is executed. 


Note 


When the function specified by func executes a return statement, the program resumes execution 
from the point at which the signal was generated, but if the signal is a value corresponding to 
exception handling defined by SIGFPE or the implementation, the behavior is undefined. 


Error Conditions 


If the processing to be executed in the event of signal generation cannot be registered, the value of 
SIG_ERR is set in errno. 
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7.9.2 raise Function 


Function 


Generates a signal in the executing program. 


#include <signal.h> 
int sig ; 
int ret ; 


Calling 
procedure 
ret=raise (sig) ; 


Parameters : ; : 
Return value 


Generates the signal corresponding to the signal number specified by sig in the executing program. 
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7.10  <stdarg.h> 


Overview 


Enables referencing of variable arguments for functions with such arguments. 


Definition Names 


Definition Name Type 


va_list Macro name 
va_start Macro 
va_arg Macro 
va_end Macro 


Description 


Indicates the types of variables used in common by the 
va_start, va_arg, and va_end macros in order to reference 
variable arguments. 


Executes initialization processing for performing variable 
argument referencing. 


Enables referencing of the argument following the argument 
currently being referenced for a function with variable 
arguments. 


Terminates referencing of the arguments of a function with 
variable arguments. 


The above macro name is implementation-defined. 


An example of a program using the macros defined by this standard include file is shown below. 
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Example 


1 fincluck <«<stdico.hs 
z ffinclude <cstdarg. ho 
3 
4 extern void prlistlintk comt, ..5; 
= 
6 maint } 
¥ { 
8 pelist(1, 1); 
9 pelist(?, 4, 5, 6); 
10 pelisti(5, 1, 2, 32, 4, 5); 
11 } 
12 
13 void prlistiint cout, ...) 
i4 if 
15 va_list ap; 
16 int i; 
17 
18 Va_startiap, count) ; 
19 for{i=0; iccoumt; i++) 
20 printéi("td", walarglap, int); 
z1 peatchar (' yn! 4; 
ZZ va_encdiap) ; 
Explanation 


In this example, the number of data items to be output is specified in the first argument, and 
function prlist is implemented, outputting that number of subsequent arguments. 


In line 18, the variable argument reference is initialized by va_start. Each time an argument is 
output, the next argument is referenced by the va_arg macro (line 20). In the va_arg macro, the 
type name of the argument (in this case, int type) is specified in the second argument. 


When argument referencing ends, the va_end macro is called (line 22). 
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— 


7.10.1 va_start Macro 


va_start Macro 
Description | Executes initialization processing for referencing variable parameters. 


#include <stdarg.h> 
Calling va_list ap; 


procedure 
va_start (ap, parmN) ; 


1 va_list type Variable for accessing variable 
Parameters parameters 
parmN type Identifier of rightmost argument 


Return value} Normal 


The va_start macro initializes ap for subsequent use by the va_arg and va_end macros. 


The parameter parmN is the identifier of the rightmost parameter in the parameter list in the 
external function definition (the one just before the, ...). 


Note 


To reference a function with no variable name, the va_start macro call must be executed first of 
all. 
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7.10.2 va_arg Macro 


va_arg [Macro | 


Description | Enables referencing of the argument following the argument currently a 
referenced for a function with variable arguments. 


#include <stdarg.h> 
va_list ap; 


Calling oe — 


procedure 
ret=va_arg(ap,type) ; 


a 


va_list type Variable for accessing variable 
Parameters parameters 
type Type name Type of parameter to be 
accessed 


[Type Type type specified by the second argument of parameters 


Return value} Normal Parameter value 
Abnormal 


A variable of the va_list type initialized by the va_start macro is specified in the first parameter. 
The value of ap is updated each time va_arg is used, and as a result variable parameters are 
returned sequentially as return values of this macro. 


Specify the type of the argument to be referenced at the type location in the calling procedure. 
Note 
The ap parameter must be the same as the ap initialized by va_start. 


It will not be possible to reference the parameters correctly if a type for which the size is changed 
by type conversion is specified when char type, unsigned char type, short type, unsigned short 
type, or float type in the function argument is specified as the type of type. If this kind of type is 
specified, operation will be undefined. 
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7.10.3 va_end Macro 


Terminates referencing of the arguments of a function with variable arguments. 


#include <stdarg.h> 
Calling va_list ap; 


procedure 
va_end(ap) ; 


Parameters 


1 va_list type Variable for accessing variable 
arguments 


Type 
Return value 


Note 


The ap parameter must be the same as the ap initialized by va_start. If the va_end macro is not 
called before the return from a function, the operation of that function will be undefined. 
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7.11 <stdio.h> 


Overview 


Performs processing relating to file input/output for stream input/output. 


Definition Names 


Definition Name 


FILE 


_IOFBF 


_IOLBF 


_IONBF 


BUFSIZ 
EOF 
L_tmpnam 
SEEK_CUR 
SEEK_END 
SEEK_SET 
SYS_OPEN 


TMP_MAX 


stderr 
stdin 
stdout 


remove 


Type 
Macro name 


Macro name 


Macro name 


Macro name 


Macro name 
Macro name 
Macro name 
Macro name 
Macro name 
Macro name 
Macro name 


Macro name 


Macro name 
Macro name 
Macro name 


Function 
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Description 


Indicates a structure type that stores various control 
information including a pointer to the buffer, an error 
indicator, and an end-of-file indicator, required for stream 
input/output processing. 


Indicates full buffering of input/output as the buffer area 
usage method. 


Indicates line buffering of input/output as the buffer area 
usage method. 


Indicates non-buffering of input/output as the buffer area 
usage method. 


Indicates the buffer size required for input/output processing. 
Indicates end-of-file, that is, no more input from a file. 


Indicates the size of an array large enough to store a 
temporary file character name character string generated by 
the tmpnam function. 


Indicates a shift of the current file read/write position to an 
offset from the current position. 


Indicates a shift of the current file read/write position to an 
offset from the end-of-file position. 


Indicates a shift of the current file read/write position to an 
offset from the beginning of the file. 


Indicates the number of files for which simultaneous opening 
is guaranteed by the implementation. 


Indicates the minimum number of unique file names that 
shall be generated by the tmpnam function. 


Indicates the file pointer for the standard error file. 
Indicates the file pointer for the standard input file. 
Indicates the file pointer for the standard output file. 


Deletes the specified file. 
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Definition Name Type Description 


rename Function Changes the specified file name to the specified new file 
name. 

tmpfile Function Creates a temporary binary file. 

tmpnam Function Generates a different file name each time it is called. 

fclose Function Closes a stream input/output file. 

fflush Function Outputs stream input/output file buffer contents to the file. 

fopen Function Opens a stream input/output file under the specified file 
name. 

freopen Function Closes a currently open stream input/output file and reopens 
a new file under the specified file name. 

setbuf Function Defines and sets a stream input/output buffer area on the 
user program side. 

setvbuf Function Defines and sets a stream input/output buffer area on the 
user program side. 

fprintf Function Outputs data to a stream input/output file according to a 
format. 

fscanf Function Inputs data from a stream input/output file and converts it 
according to a format. 

printf Function Converts data according to a format and outputs it to the 
standard output file (stdout). 
according to a format. 

sprintf Function Converts data according to a format and outputs it to the 
specified area. 

sscanf Function Inputs data from the specified storage area and converts it 
according to a format. 

Vfprintf Function Outputs a variable parameter list to the specified stream 
input/output file according to a format. 

vprintf Function Outputs a variable parameter list to the standard output file 
according to a format. 

vsprintf Function Outputs a variable parameter list to the specified storage 
area according to a format. 

fgetc Function Inputs one character from a stream input/output file. 

fgets Function Inputs a string from a stream input/output file. 

fputc Function Outputs one character to a stream input/output file. 

fputs Function Outputs a string to a stream input/output file. 

getc Function Inputs one character from a stream input/output file. 
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Definition Name 
getchar 

gets 

putc 

putchar 

puts 

ungetc 


fread 


fwrite 


fseek 


ftell 


rewind 


clearerr 
feof 
ferror 


perror 


Type 

Function 
Function 
Function 
Function 
Function 
Function 


Function 


Function 


Function 


Function 


Function 


Function 
Function 
Function 


Function 


Description 

Inputs one character from the standard input file. 
Inputs a string from the standard input file. 

Outputs one character to a stream input/output file. 
Outputs one character to the standard output file. 
Outputs a string to the standard output file. 
Returns one character to a stream input/output file. 


Inputs data from a stream input/output file to the specified 
storage area. 


Outputs data from a storage area to a stream input/output 
file. 


Shifts the current read/write position in a stream input/output 
file. 


Obtains the current read/write position in a stream 
input/output file. 


Shifts the current read/write position in a stream input/output 
file to the beginning of the file. 


Clears the error state of a stream input/output file. 
Tests for the end of a stream input/output file. 
Tests for stream input/output file error state. 


Outputs an error message corresponding to the error number 
to the standard error file (stderr). 


The above macro names are all implementation-defined. 


An example of a program that performs a series of input/output processing operations for a stream 


input/output file is shown below. 
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Example 


if fiinclucde cstdio.h> 
2 
3 maint } 
4 { 
a int c; 
6 FILE *ifp, *ofp; 
fi 
8 if {lifp=fopen("INEUr.paT ","x"j)==nmEL) ¢ 
] fpeinte (stderr, "“carnmot open input file\n") ; 
10 eruit (1) ; 
11 } 
1? if (lofp=fopen("OUTFUT. DAT ","H")) ==HULL) { 
13 Epeinté (stderr, “carmot open output filein'); 
i4 enuit (1) ; 
15 } 
16 while [fc=getclifp))! =Bor) 
1? Putct(e, ofp) ; 
ig folose ti fp) ; 
19 foloses(ofp) ; 
20 
Explanation 


This program copies the contents of file INPUT.DAT to file OUTPUT.DAT. 


Input file INPUT.DAT is opened by the fopen function in line 8, and output file OUTPUT.DAT is 
opened by the fopen function in line 12. If opening fails, NULL is returned as the return value of 
the fopen function, an error message is output, and the program is terminated. 


If the fopen function ends normally, pointers to the data (FILE type) that stores information on the 
opened files is returned; these are set in variables ifp and ofp. 


After successful opening, input/output is performed using these FILE type data items. 


When file processing ends, the files are closed with the fclose function. 
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7.11.1 remove Function 


Deletes the specified file. 


#include <stdio.h> 
const char *pathname; 
int ret; 


Calling 
procedure 
ret=remove (pathname) ; 


Parameters 


const char type be deleted 
Return value 
Nonzero 


Deletes the file with the file name pointed to by pathname. 
Note 


When the remove function is executed on an open file, its operation depends on the compiler. 
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7.11.2 rename Function 


Changes the name of the specified file to the specified new file name. 


#include <stdio.h> 
const char *old, *new; 
int ret; 


Calling 
procedure 


ret=rename (old,new) ; 


Type 


Pointer indicating const | Pointer indicating old file 
Parameters char type name 


Pointer indicating const | Pointer indicating new file 
char type 


Return value 


Abnormal | Nonzero 


The file with the file name pointed to by o/d is then made identifiable by the file name pointed to 
by new. The old file name is deleted. 


If this operation fails, the file name of the file remains the same. 


7.11.3 tmpfile Function 


Description | Creates a temporary binary file. 


#include <stdio.h> 


Calling FILE *ret; 


procedure 
ret=tmpfile( ); 


No. Meaning 
Parameters | 
Pointer to FILE type 
Return value File pointer for the created file 


The file created by the tmpfile function is automatically deleted when it is closed, or when the 
program ends. 


This file can be used for updating. 
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7.11.4  tmpnam Function 


Function 


Generates a different file name each time it is called. 


#include <stdio.h> 
Calling char *s, *ret; 
procedure 


ret=tmpnam(s) 


[Ns see [ne 
Parameters 


Pointer indicating Pointer to storage area for storing 
char type generated file name 


[Type | [Type —_| Pointer to char type 


Return value} Normal Pointer to file name 
Abnormal 


The tmpnam function generates a different file name each time it is called, up to TMP_MAX 
times. 


If s is a null pointer, the tmpnam function allocates a storage area that stores the file name, 
generates a file name in that area, and returns the start address of the area. 


If s is not a null pointer, s is assumed to point to a storage area L_tmpnam bytes in size, the file 
name is written to that storage area, and the value of s is returned directly as the return value. 


Note 


A storage area of at least L_tmpnam bytes should be provided as the file name area. If the 
tmpnam function is called more than TMP_MAX times, the behavior is implementation-defined. 
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7.11.5 — fclose Function 


fclose Function 


Closes a stream input/output file. 


#include <stdio.h> 
FILE *£p; 


Calling : 
procedure |720¢ ret; 
ret=fclose (fp) ; 


Parameters 


FILE type 
Return value 
Nonzero 


The fclose function closes the stream input/output file indicated by file pointer fp. 


If the output file of the stream input/output file is open and data that is not output remains in the 
buffer, that data is output to the file before it is closed. 


If the input/output buffer was automatically allocated by the system, it is cancelled. 


7.11.6 = fflush Function 


Outputs stream input/output file buffer contents to the file. 


#include <stdio.h> 
FILE *fp; 


ee int ret; 


procedure 
ret=fflush(fp) ; 


Parameters fp Pointer indicating _| File pointer 
FILE type 


Abnormal | Nonzero 


When an output file of the stream input/output file is open, the fflush function outputs the contents 
of the buffer that is not output for the stream input/output file specified by file pointer fp to the 
file. If an input file is open, the ungetc function specification is invalid. 
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7.11.7 fopen Function 


Function 


Opens a stream input/output file under the specified file name. 


#include <stdio.h> 
FILE *ret; 
const char *fname, *mode; 


Calling 
procedure 
ret=fopen(fname, mode) 


fname Pointer indicating Pointer to string indicating file 
Parameters const char type name 


Pointer indicating Pointer to string indicating file 
const char type access mode 


Pointer to FILE type 


Return value File pointer indicating file information on opened file 


The fopen function opens the stream input/output file whose file name is the string pointed to by 
fname. Ifa file that does not exist is opened in write mode or append mode, a new file is created 
wherever possible. When an existing file is opened in write mode, writing processing is 
performed from the beginning of the file, and previously written file contents are erased. 


When a file is opened in append mode, write processing is performed from the end-of-file 
position. When a file is opened in update mode, both input and output processing can be 
performed on the file. However, input cannot directly follow output without intervening execution 
of the fflush, fseek, or rewind function. Similarly, output cannot directly follow input without 
intervening execution of the fflush, fseek, or rewind function. 


A string indicating the opening method may be added after the string indicating the file access 
mode. 
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7.11.8 freopen Function 


i. Closes a currently open stream input/output file and reopens a new file under 
Description | the specified file name. 


#include <stdio.h> 
const char *fname, *mode; 


ae: FILE *réty *£p; 


procedure 


ret=freopen(fname, mode, 


fp); 


1 fname Pointer indicating Pointer to string indicating new 
const char type file name 
Parameters 2 mode Pointer indicating | Pointer to string indicating file 
const char type access mode 
3 fp Pointer indicating | File pointer of currently open 
FILE type stream input/output file 
Pointer to FILE type 


Return value fp 


The freopen function first closes the stream input/output file indicated by file pointer fp (the 
following processing is carried out even if this close processing is unsuccessful). Next, the 
freopen function opens the file indicated by file name fname for stream input/output, reusing the 
FILE structure pointed to by fp. 


The freopen function is useful when there is a limit on the number of files being opened at one 
time. 


The freopen function normally returns the same value as fp, but returns a null pointer if an error 
occurs. 
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7.11.9 | setbuf Function 


Defines and sets a stream input/output buffer area on the user program side. 


#include <stdio.h> 
FILE *fp; 
char buf [BUFSIZ]; 


setbuf (fp, buf); 


Calling 
procedure 


Pointer indicating FILE type File pointer 
Pointer indicating char type array | Pointer to buffer area 


Return value 


Parameters 


The setbuf function defines the storage area pointed to by buf so that it can be used as an 
input/output buffer area for the stream input/output file indicated by file pointer fp. As a result, 
input/output processing is performed using a buffer area of size BUFSIZ. 
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7.11.10 setvbuf Function 


setvbuf Function 


Description | Defines and sets a stream input/output buffer area on the user program side. 


#include <stdio.h> 
FILE *f£p; 
Calling char *buf; 
procedure int type, ret; 
size t size; 


ret=setvbuf (fp, buf, type, size); 


Parameters 


fp Pointer indicating File pointer 
FILE type 

buf Pointer indicating | Pointer to buffer area 
char type 


No. 
1 
2 
type int type Buffer management method 
size_t type Size of buffer area 


Type int 
Return value| Normal 


The setvbuf function defines the storage area pointed to by buf so that it can be used as an 
input/output buffer area for the stream input/output file indicated by file pointer fp. 


There are three ways of using this buffer area, as follows: 


(1) When _IOFBF is specified for type 
Input/output is fully buffered. 


(2) When _IOLBF is specified for type 


Input/output is line buffered. That is, input/output data is fetched from the buffer area when a 
new-line character is written, when the buffer area is full, or when input is requested. 


(3) When _IONBF is specified for type 
Input/output is unbuffered. 


The setvbuf function normally returns zero, but if an invalid value is given in type or size, or if 
a request, such as the request for the buffer area usage method, cannot be accepted, nonzero is 
returned. 
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Note 


The buffer area must not be released before the opened stream input/output file is closed. Also, 
the setvbuf function must be used between opening of the stream input/output file and execution 
of input/output processing, 


711.11 fprintf Function 


fprintf Function 


Outputs data to a stream input/output file according to a format. 


#include <stdio.h> 
FILE *fp; 


Calling const char *control; 
procedure | int ret; 


ret=fprintf(fp, control, [,arg] ...); 


1 fp Pointer indicating _ | File pointer 
FILE type 
Parameters 2 control Pointer indicating | Pointer to string indicating 
const char type format 
Not stipulated List of data to be output 
according to format 


[Type | 
Return value Number of characters converted and output 


Negative value 


The fprintf function converts and edits argument arg according to the string that indicates the 
format pointed to by control, and outputs the result to the stream input/output file indicated by file 
pointer fp. 


The fprintf function returns the number of data items converted and output, or a negative value if 
an error occurs. 


The format specifications are shown below. 


(1) Overview of formats 
The character string that represents the format is made up of two kinds of string. 
(a) Ordinary characters 


A character other than a specification beginning with % shown in (b) is output unchanged. 
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(b) Conversion specification 


A conversion specification is a string beginning with % that specifies the conversion 
method for the following argument. The conversion specification format conforms to the 
following rules: 


[*] (*] ; oe , 
‘a [Fg ay Field width] || Precision] || [Por seneter size specification] Conversion string 


If there is no parameter to be actually output for this conversion specification, the behavior is 
undefined. Also, if the number of parameters to be actually output is greater than the conversion 
specification, the excess parameters are ignored. 


(2) Description of conversion specifications 
(a) Flags 
Flags specify modifications to the data to be output, such as addition of a sign. The types 
of flag that can be specified, and their meanings, are shown in table 7.5. 


Table 7.5 Flag Types and Their Meanings 


Type Meaning 


- If the number of converted data characters is less than the width of the field, the data will 
be output left-justified within the field. 


+ A plus or minus sign will be prepended to the result of a signed conversion. 


space If the first character of a signed conversion result is not a sign, a space will be prepended 
to the result. If the space and + flags are both specified, the space flag will be ignored. 


# The converted data is to be modified according to the conversion types described in 
table 7.7. 


(1) For, d, i, s, and u conversions 
This flag is ignored. 
(2) For o conversion 
The converted data is prepended with 0. 
(3) For x or X conversion 
The converted data is prepended with Ox (or OX) 
(4) For e, E, f, g, and G conversions 


A decimal point is output even if the converted data has no fractional part. With g and 
G conversions, the 0 appended to the converted data cannot be removed. 


(b) Field width 
The number of characters in the converted data to be output is specified as any decimal 
number. 
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If the number of converted data characters is less than the width of the field, the data is 
prepended with spaces up to the width of the field. (However, if '-' is specified as a flag, 
spaces are appended to the data.) 

If the number of converted data characters exceeds the width of the field, the width of the 
field is extended to allow the converted result to be output. 

If the field width specification begins with 0, 0 characters, not spaces, are prepended to the 
output data. 


(c) Precision 


The precision of the converted data is specified according to the type of conversion, as 
described in table 7.7. 


The precision is specified in the form of a period (.) followed by a decimal integer. If the 
decimal integer is omitted, 0 is assumed to be specified. 


If the specified precision is incompatible with the field width specification, the field width 
specification is ignored. 


The precision specification has the following meanings according to the conversion type. 
(1) For d, i, 0, u, x, and X conversions 
The minimum number of digits in the converted data is specified. 
(2) For e, E, and f conversions 
The number of digits after the decimal point in the converted data is specified. 
(3) For g and G conversions 
The maximum number of significant digits in the converted data is specified. 
(4) For s conversion 


The maximum number of printed digits is specified. 


(d) Parameter size specification 


For d, i, 0, u, x, X, e, E, f, g, and G conversions (see table 7.7), specifies the size (short 
type, long type, or long double type) of the data to be converted. In other conversions, this 
specification is ignored. Table 7.6 shows the types of size specification and their 
meanings. 


Table 7.6 Parameter Size Specification Types and Meanings 


Type 
h 


Meaning 


In d, i, 0, u, xX, and X conversions, specifies that the data to be converted is of short type 
or unsigned short type. 


In d, i, 0, u, x, and X conversions, specifies that the data to be converted is of long type, 
unsigned long type, or double type. 


In e, E, f, g, and G conversions, specifies that the data to be converted is of long double 


type. 
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(e) Conversion specifier 


Specifies the format into which the conversion data is to be converted. 


If the data to be converted is union or aggregate type, or is a pointer indicating those types, 
the behavior is undefined except when a character array is converted by s conversion or 
when a pointer is converted by p conversion. Table 7.7 shows the conversion specifiers 
and conversion methods. If a lower-case letter not shown in this table is specified as the 
conversion specifier, the behavior is undefined. The behavior if another character is 


specified depends on the compiler. 


Table 7.7 Conversion Specifiers and Conversion Methods 


Data Type 
Conversion Conversion Subject to 
Specifier Type Conversion Method Conversion 
d dconversion _ int type data is converted to asigned int type 
OO, decimal string. d conversion and i P 
i i conversion P int type 
conversion have the same 
specification. 
° o conversion _ int type data is converted to an int type 
unsigned octal string. 
u uconversion _ int type data is converted to an int type 
unsigned decimal string. 
x x conversion — int type data is converted to unsigned _ int type 
hexadecimal. a, b, c, d, e, and f are 
used as hexadecimal characters. 
Xx X conversion _ int type data is converted to unsigned __ int type 


hexadecimal. A, B, C, D, E, and F are 
used as hexadecimal characters. 


Notes on Precision 


The precision specification indicates the 
minimum number of characters output. If 
the number of converted data characters 
is less than the width of the field, the 
string is prepended with zeros. If the 
precision is omitted, 1 is assumed. If 
conversion and output of data with a value 
of 0 is attempted with 0 specified as the 
precision, nothing will be output. 


mn 


fconversion double type data is converted to a double type 
decimal string with the format [-] 
ddd.ddd. 


The precision specification indicates the 
number of digits after the decimal point. If 
there are characters after the decimal 
point, at least one digit is output before 
the decimal point. If the precision is 
omitted, 6 is assumed. If 0 is specified as 
the precision, the decimal point and 
subsequent characters are not output. 
The output data is rounded. 
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Table 7.7 


Conversion Conversion 
Specifier Type 


e e conversion double type data is converted to a 


Conversion Method 


Data Type 
Subject to 


Conversion Specifiers and Conversion Methods (cont) 


Conversion Notes on Precision 


double type 


decimal string with the format [-] 
d.dddet+dd. At least two digits are 


output as the exponent. 


E E conversion double type data is converted to a 


double type 


decimal string with the format [-] 
d.dddE+dd. Atleast two digits are 


output as the exponent. 


g gconversion Whether f conversion format output 


double type 


(or G or e conversion (or E conversion) 


conversion) 


format output is performed is 
determined by the value to be 
converted and the precision value that 


specifies the number of significant 
digits, and double type data is output. 
If the exponent of the converted data is 
less than -4, or larger than the 
precision that indicates the number of 
significant digits, conversion to e (or E) 


format is performed. 


c c conversion _ int type data is converted to unsigned __ int type 
char data, with conversion to the 
character corresponding to that data. 


s s conversion The number of characters specified 


Pointer to 


by the precision from a string pointed char type 
to by data of pointer to char type are 

output up to, but not including, the null 

character indicating the end of the 

string. (Null characters are not output. 

Space, horizontal tab, and new line 

characters are not included in the 


converted characters.) 


p pconversion With data as a pointer, conversion is 
performed to a string of compiler- 


Pointer to 
void type 


defined printable characters. 


n no conversion Data is regarded as pointer to int type, Pointer to int 


is performed. and the number of characters output so type 
far is set in the storage area pointed to 


by that data. 


% no conversion % is output. 
is performed. 
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double type 


The precision specification indicates the 
number of digits after the decimal point. 
The format is such that at least one digit is 
output before the decimal point in the 
converted characters, and a number of 
digits equal to the precision are output 
after the decimal point. If the precision is 
omitted, 6 is assumed. If 0 is specified as 
the precision, characters after the decimal 
point are not output. The output data is 
rounded. 


The precision specification indicates the 
maximum number of significant digits in 
the converted data. 


The precision specification is invalid. 


The precision specification indicates the 
number of characters to be output. If the 
precision is omitted, characters are output 
up to, but not including, the null character 
in the string pointed to by the data. (Null 
characters are not output. Space, 
horizontal tab, and new line characters 
are not included in the converted 
characters.) 


The precision specification is invalid. 


(f) * specification for field width or precision 


* can be specified as the field width or precision specification value. In this case, the value 
of the parameter corresponding to the conversion specification is used as the field width or 
precision specification value. If this parameter has a negative field width, flag '"' is 
interpreted as being specified for the positive field width. If the parameter has a negative 
precision, the precision is interpreted as being omitted. 


7.11.12 fscanf Function 


Inputs data from a stream input/output file and converts it according to a format. 


#include <stdio.h> 
FILE *fp; 

const char *control; 
int ret; 


Calling 
procedure 


ret=fscanf (fp, control [,ptr] ...); 


a 


Pointer indicating File pointer 
FILE type 
Parameters 2 control Pointer indicating Pointer to string indicating 
const char type format 
3 ptr Pointer indicating Pointer to storage area that 
data type holds input data 


Return value Number of data items successfully input and converted 


The fscanf function inputs data from the stream input/output file indicated by file pointer fp, 
converts and edits it according to the string indicating the format pointed to by control, and stores 
the result in the storage area pointed to by ptr. 


If input data ends before input data conversion is performed: EOF 


The format specifications for inputting data are shown below. 


(1) Overview of formats 
The string that represents the format is made up of the following three kinds of string. 
(a) Space characters 


If a space (''), horizontal tab (‘\t'), or new-line character (‘\n') is specified, processing is 
performed to skip to the next non-white-space character in the input data. 
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(b) Ordinary characters 


If a character that is neither one of the white-space characters listed in (a) nor % is 
specified, one input data character is input. The input character must match a character 
specified in the string that represents the format. 


(c) Conversion specification 
A conversion specification is a string beginning with % that specifies the method of 


converting the input data and storing it in the area pointed to by the following argument. 
The conversion specification format conforms to the following rules: 


% [*] [Field width] [Converted data size] Conversion string 


If there is no pointer to the storage area that holds input data for the conversion 
specification in the format, the behavior is undefined. Also, if a pointer to a storage area 
that holds input data remains when the format is exhausted, that pointer is ignored. 


(2) Description of conversion specifications 
(a) * specification 
Suppresses storage of the input data in the storage area pointed to by the parameter. 
(b) Field width 


The maximum number of characters in the data to be input is specified as a decimal 
number. 


(c) Converted data size 


For d, 1, 0, u, x, X, e, E, and f conversions (see table 7.9), specifies the size (short type, 
long type, or long double type) of the converted data. In other conversions, this 
specification is ignored. Table 7.8 shows the types of size specification and their 
meanings. 


Table 7.8 Converted Data Size Specification Types and Meanings 


Type Meaning 
h In d, i, 0, u, Xx, and X conversions, specifies that the converted data is of short type. 


| In d, i, 0, u, X, and X conversions, specifies that the converted data is of long type. 
In e, E, and f conversions, specifies that the converted data is of double type. 


L In e, E, and f conversions, specifies that the converted data is of long double type. 
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(d) Conversion specifier 


The input data is converted according to the type of conversion specified by the conversion 
specifier. However, processing is terminated if a white-space character is read, if a 
character for which conversion is not permitted is read, or if the specified field width is 
exceeded. 


Table 7.9 Conversion Specifiers and Conversion Methods 


Conversion Conversion Data Type Subject 
Specifier Type Conversion Method to Conversion 

d dconversion A decimal string is converted to integer type data. Integer type 

i iconversion A decimal string with a sign prepended, or a decimal string with u (U) Integer type 


or | (L) appended is converted to integer type data. A string beginning 
with Ox (or OX) is interpreted as hexadecimal, and the string is converted 
to int type data. A string beginning with 0 is interpreted as octal, and the 
string is converted to int type data. 


fe) oconversion An octal string is converted to integer type data. Integer type 
u uconversion An unsigned decimal string is converted to integer type data. Integer type 
x x conversion A hexadecimal string is converted to integer type data. Integer type 
; There is no difference in meaning between x conversion and X conversion. 
X X conversion 
s s conversion Characters are converted as a single string until a space, horizontal tab, Character type 
or new-line character is read. A null character is appended at the end of 
the string. (The string in which the converted data is set must be large 
enough to include the null character.) 
Cc c conversion One character is input. The input character is not skipped even if it is a char type 
white-space character. To read only non-white-space characters, specify 
%18S. lf the field width is specified, the number of characters equivalent 
to that specification are read. In this case, therefore, the storage area that 
holds the converted data must be of the specified size. 
e e conversion A string indicating a floating-point number is converted to floating-point Floating-point type 
=~... __,__ type data. There is no difference in meaning between the e conversion 
E E conversion 


and E conversion, or between the g conversion and G conversion. 
f f conversion The input format is a floating-point number that can be represented by 
T_T the strtod function. 


g g conversion 

G G conversion 

p pconversion A string converted by p conversion in the fprintf function is Pointer to void type 
converted to pointer type data. 

n 


no conversion Data input is not performed; the number of data characters input so faris Integer type 
is performed. set. 
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Table 7.9 Conversion Specifiers and Conversion Methods (cont) 


Conversion Conversion Data Type Subject 
Specifier Type Conversion Method to Conversion 
[ [conversion A sequence of characters is specified after [, followed by ]. This character Character type 


sequence defines a sequence of characters comprising a string. If the 

first character of the character sequence is not a circumflex (4), the input 
data is input as a single string until a character not in this character 
sequence is first read. If the first character is “, the input data is input as a 
single string until a character sequence character other than ° is first read. 
A null character is automatically appended at the end of the input string (so 
the string in which the converted data is set must be large enough to include 
the null character). 


% no conversion % is read. None 
is performed. 


If the conversion specifier is a lower-case letter not shown in table 7.9, the behavior is undefined. 
For other characters, the behavior is implementation-defined. 


7.11.13 printf Function 


printf |Function | 


Converts data according to a format and outputs it to the standard output fi Fonction le 
Description (stdout). 


#include <stdio.h> 
const char *control; 
int ret; 


Calling 
procedure 
ret=printf (control [,arg] a 


control Pointer indicating teenie | to string indicating 
Parameters const char type format 
Type according to | Data to be output according to 
format format 


[Type | 
Return value Number of characters converted and output 


Negative value 


The printf function converts and edits parameter arg according to the string that indicates the 
format pointed to by control, and outputs the result to the standard output file (stdout). 


For details of the format specifications, see section 7.11.11, fprintf Function. 
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7.11.14 scanf Function 


scanf Function 


— Inputs data from the standard input file (stdin) and converts it according to a 
Description forriak 


#include <stdio.h> 
Calling const char *control; 


procedure |int ret; 
ret=scanf (control [,ptr] ..); 


control Pointer indicating Pointer to string indicating 
Parameters const char type format 
Pointer indicating Pointer to storage area that 
any data holds input and converted data 


Return value Number of data items successfully input and converted 


The scanf function inputs data from the standard input file (stdin), converts and edits it according 
to the string indicating the format pointed to by control, and stores the result in the storage area 
pointed to by ptr. 


The scanf function returns the number of data items successfully input and converted as the return 
value. EOF is returned if the standard input file ends before the first conversion. 


For details of the format specifications, see section 7.11.12, fscanf Function. 


Note: In %e conversion, specify | for double type, and specify L for long double type. The 
default type is float. 
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7.11.15 sprintf Function 


Converts data according to a format and outputs it to the specified area. 


#include <stdio.h> 
char *s ; 


Calling const char *control; 
procedure | int ret; 


ret=sprintf(s, control [, arg] 


a 


Pointer indicating Pointer to storage area to which 
char type data is to be output 
Parameters 2 control Pointer indicating | Pointer to string indicating 
const char type format 
3 arg Type according to | Data to be output according to 
format format 


Return value} Normal Number of characters converted 


| Abnormal _| 


The sprintf function converts and edits parameter arg according to the string that indicates the 
format pointed to by control, and outputs the result to the storage area pointed to by s. 


A null character is appended at the end of the converted and output string. This null character is 
not included in the return value (number of characters output). 


For details of the format specifications, see section 7.11.11, fprintf Function. 
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7.11.16 sscanf Function 


sscanf |Function 


Inputs data from the specified storage area and converts it according Function | a 
Description | ft mat. 


#include <stdio.h> 
Calling const char *s, *control; 
procedure |int ret; 


ret=sscanf(s, control [, ptr] ...) 


a 


Pointer indicating Storage area containing data to 
const char type be input 
Parameters 2 control Pointer indicating | Pointer to string indicating 
const char type format 
3 ptr Pointer indicating Pointer to storage area that 
data type holds input and converted data 
Type int 


Return value Number of data items successfully input and converted 
| Abnormal | EOF 


The sscanf function inputs data from the storage area pointed to by s, converts and edits it 
according to the string indicating the format pointed to by control, and stores the result in the 
storage area pointed to by ptr. 


The sscanf function returns the number of data items successfully input and converted. EOF is 
returned if the input data ends before the first conversion. 


For details of the format specifications, see section 7.11.12, fscanf Function. 
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7.11.17 vfprintf Function 
prin 


a Outputs a variable parameter list to the specified stream input/output file according 
Description | 1, 4 format. 


#include <stdarg.h> 
#include <stdio.h> 
FILE *fp ; 

const char *control; 
va_list arg; 

ate ret; 


Calling 
procedure 


ret=vfprintf(fp, control, arg) ; 


1 Pointer indicating File pointer 
FILE type 
Paromigtals 2 control Pointer indicating Pointer to string indicating 
const char type format 


fp 
va_list type Argument list 


int 


Type 
Return value Number of characters converted and output 
Negative value 


The vfprintf function sequentially converts and edits a variable parameter list according to the 
string that indicates the format pointed to by control, and outputs the result to the stream 
input/output file indicated by fp. 


The vfprintf function returns the number of data items converted and output, or a negative value if 
an error occurs. 


With the vfprintf function, the va_end macro is not invoked. 
For details of the format specifications, see section 7.11.11, fprintf Function. 
Note 


Parameter arg, indicating the argument list, must have been initialized by the va_start and va_arg 
macros. 
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7.11.18 vprintf Function 


we Outputs a variable parameter list to the standard output file (stdout) according 
Description | to 3 format. 


#include <stdarg.h> 

#include <stdio.h> 
Calling const char *control; 
procedure |va_list arg; 

int ret; 


ae arg) ; 


= Pointer indicating Pointer to string a 
Parameters const char type format 


| 6200 | larg va_list type Argument list 
ar 


Return value Number of characters converted and output 


| Abnormal_| Negative value 


The vprintf function sequentially converts and edits a variable parameter list according to the 
string that indicates the format pointed to by control, and outputs the result to the standard output 
file. 


The vprintf function returns the number of data items converted and output, or a negative value if 
an error occurs. 


With the vprintf function, the va_end macro is not invoked. 
For details of the format specifications, see section 7.11.11, fprintf Function. 
Note 


Parameter arg, indicating the argument list, must have been initialized by the va_start and va_arg 
macros. 
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7.11.19 vsprintf Function 


vsprintf Function 


Outputs a variable parameter list to the specified storage area according to a 
format. 


#include <stdarg.h> 
#include <stdio.h> 
char *s; 

const char *control; 
va_list arg; 

int ret; 


Calling 
procedure 


ret=vsprintf(s, control, arg); 


1 Ss Pointer indicating | Pointer to storage area to which 
char type data is to be output 
Pareto 2 control Pointer indicating Pointer to string indicating 
const char type format 


va_list type Argument list 


Type int 
Return value Number of characters converted 


Negative value 


The vsprintf function sequentially converts and edits a variable parameter list according to the 
string that indicates the format pointed to by control, and outputs the result to the storage area 
pointed to by s. 


A null character is appended at the end of the converted and output string. This null character is 
not included in the return value (number of characters output). 


For details of the format specifications, see section 7.11.11, fprintf Function. 
Note 


Parameter arg, indicating the argument list, must have been initialized by the va_start and va_arg 
macros. 


Rev. 1.0, 09/98, page 268 of 476 
HITACHI 


7.11.20 fgetc Function 


Function 
Inputs one character from a stream input/output file. 


#include <stdio.h> 
FILE *fp; 
int ret; 


Calling 
procedure 


ret=fgetc(fp) ; 


eee a a 
Parameters 


Pointer indicating | File pointer 
FILE type 


Type 


End-of-file: EOF 
Return value} Normal 


Otherwise: Input character 


The fgetc function inputs one character from the stream input/output file indicated by file pointer 
fp. 


The fgetc function normally returns the input character, but returns EOF at end-of-file or if an 
error occurs. At end-of-file, the end-of-file indicator for that file is set. 


Error Conditions 


If a read error occurs, the error indicator for that file is set. 
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7.11.21 fgets Function 


fgets Function 
Inputs a string from a stream input/output file. 


#include <stdio.h> 
' char *s, *ret; 
Calling £ te n; 


procedure FILE *fp; 


ret=fgets(s, n, 


a 


Pointer indicating Pointer to storage area to which 
char type string is input 
Parameters 2 n int type Number of bytes of storage 
area to which string is input 
3 fp Pointer indicating | File pointer 
FILE type 


Type Pointer to char type 


End-of-file: NULL 
Otherwise: s 


Return value} Normal 


Abnormal | NULL 


The fgets function inputs a string from the stream input/output file indicated by file pointer fp to 
the storage area pointed to by s. 


The fgets function performs input up to the (n—1)th character or a new-line character, or until end- 
of-file, and appends a null character at the end of the input string. 


The fgets function normally returns s, the pointer to the storage area to which the string is input, 
but returns a null pointer at end-of-file or if an error occurs. 


Note 


The contents of the storage area pointed to by s do not change at end-of-file, but are undefined if 
an error occurs. 
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rT el eens a 7 oe 


7.11.22 fputc Function 


Outputs one character to a stream input/output file. 


#include <stdio.h> 
FILE *fp ; 
Int c, ret; 


Calling 
procedure 
ret=fputc(c, fp); 


p ‘ int type Character to be output 
arameters 


2 fp Pointer indicating File pointer 
FILE type 
Return value Output character 


The fputc function outputs character c to the stream input/output file indicated by file pointer fp. 
The fputc function normally returns c, the output character, but returns EOF if an error occurs. 
Error Conditions 


If a write error occurs, the error indicator for that file is set. 
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7.11.23 fputs Function 


Function 


Outputs a string to a stream input/output file. 


#include <stdio.h> 


: const char *s ; 
Calling int ret; 
procedure |ping *£p; 


ret=fputs(s 


Pointer indicating tts to string to be output 
Parameters const char type 
Pointer indicating File pointer 
FILE type 


‘Type | 


Return value} Normal 
Abnormal | Nonzero 


The fputs function outputs the string up to the character preceding the null character pointed to by 
s to the stream input/output file indicated by file pointer fp. The null character indicating the end 
of the string is not output. 


The fputs function normally returns zero, but returns nonzero if an error occurs. 
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7.11.24 getc Function 


Function 
Description | Inputs one character from a stream input/output file. 


#include <stdio.h> 
FILE *fp ; 
tne ret ; 


Calling 
procedure 


ret=getc(fp) ; 


eee |e es 
Parameters 


Pointer indicating File pointer 
FILE type 


End-of-file: EOF 
Return value] Normal Otherwise: Input character 


The getc function inputs one character from the stream input/output file indicated by file pointer 
fp. 


The getc function normally returns the input character, but returns EOF at end-of-file or if an error 
occurs. At end-of-file, the end-of-file indicator for that file is set. 


Note 


As getc is implemented as a macro in some compilers, it cannot get an address. For use as a 
function (when getting an address, etc.), the fgetc function should be used. 


Error Conditions 


If a read error occurs, the error indicator for that file is set. 
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7.11.25 getchar Function 


Function 


Inputs one character from the standard input file (stdin). 


#include <stdio.h> 
Calling int ret ; 
procedure 


ret=getchar ( 


ee 
Parameters 


Type 


End-of-file: EOF 
Return wl as TE malin i 


Otherwise: Input character 


The getchar function inputs one character from the standard input file (stdin). 


The getchar function normally returns the input character, but returns EOF at end-of-file or if an 
error occurs. At end-of-file, the end-of-file indicator for that file is set. 


Note 


As getchar is implemented as a macro in some compilers, it cannot get an address. For use as a 
function (when getting an address, etc.), the fgetc function should be used. 


Error Conditions 


If a read error occurs, the error indicator for that file is set. 
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7.11.26 gets Function 


Function 
Inputs a string from the standard input file (stdin). 


#include <stdio.h> 
char *ret, *s; 


Calling 
procedure 


ret=gets(s) ; 


Parameters 


1 Ss Pointer indicating | Pointer to storage area to which 
char type string is input 


Pointer to char type 


End-of-file: NULL 
Return value} Normal Otherwise: s 


The gets function inputs a string from the standard input file (stdin) to the storage area starting at 
S. 


The gets function inputs characters up to end-of-file or until a new-line character is input, and 
appends a null character instead of a new-line character. 


The gets function normally returns s, the pointer to the storage area to which the string is input, 
but returns a null pointer at the end of the standard input file or if an error occurs. 


Note 


The contents of the storage area pointed to by s do not change at the end of the standard input file, 
but are undefined if an error occurs. 
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7.11.27  putc Function 


Function 


Outputs one character to a stream input/output file. 


#include <stdio.h> 
FILE *fp; 
int Cc, ; 


Calling 
procedure 
ret=putc(c 


ee 


e ‘ ae ee int type Character to be output 
arameters 


Pointer indicating File pointer 
FILE type 


Return value Output character 


The putc function outputs character c to the stream input/output file indicated by file pointer fp. 


The putc function normally returns c, the output character, but returns EOF if an error occurs. 
Note 


As putc is implemented as a macro in some compilers, it cannot get an address. For use as a 
function (when getting an address, etc.), the fputc function should be used. 


Error Conditions 


If a write error occurs, the error indicator for that file is set. 
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7.11.28 putchar Function 


Outputs one character to the standard output file (stdout) 


#include <stdio.h> 


Calling int c,ret ; 


rocedure 
P aa ee ) 3 


Parameters al ll int type ae to be output 


Return value Output character 


| Abnormal. | EOF 


The putchar function outputs character c to the standard output file (stdout). 
The putchar function normally returns c, the output character, but returns EOF if an error occurs. 
Note 


As putchar is implemented as a macro in some compilers, it cannot get an address. For use as a 
function (when getting an address, etc.), the fputc function should be used. 


Error Conditions 


If a write error occurs, the error indicator for that file is set. 
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7.11.29 puts Function 


Function 
Description | Outputs a string to the standard output file (stdout). 


#include <stdio.h> 
const char *s ; 
int ret; 


Calling 
procedure 


ret=puts(s) ; 


Parameters 


1 Pointer indicating Pointer to string to be output 
const char type 


Return value 


The puts function outputs the string pointed to by s to the standard output file (stdout). The null 
character indicating the end of the string is not output, but a new-line character is output instead. 


The puts function normally returns zero, but returns nonzero if an error occurs. 
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7.11.30 ungetc Function 


Returns one character to a stream input/output file. 


#include <stdio.h> 
int c, ret; 


Calling PILE -*Ep 


procedure 
ret=ungetc(c, fp); 


a 


a int type [Character tobe retuned = to be returned 
Parameters 


Pointer indicating Srarecier pe reed pointer 
FILE type 


Return value Returned character 


| Abnormal_| EOF 


The ungetc function returns character c to the stream input/output file indicated by file pointer fp. 
Unless the fflush, fseek, or rewind function is called, this returned character will be the next input 
data. 


The ungetc function normally returns character c, but returns EOF if an error occurs. 
Note 


The behavior is undefined if the ungetc function is called more than once without intervening 
fflush, fseek, or rewind function execution. When the ungetc function is executed, the current file 
position indicator for that file is moved back one position; however, if this file position indicator is 
already positioned at the beginning of the file, its value will be undefined. 
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7.11.31 fread Function 


a 
Inputs data from a stream input/output file to the specified storage area. 


#include <stdio.h> 
void *ptr; 
Calling size_t size; 
procedure |size_t on, ret; 
FILE *fp ; 


ret=fread(ptr, size, n, fp) ; 


1 ptr Pointer indicating | Pointer to storage area to which 

void type data is input 
Parameters size_t type Number of bytes in one member 
size_t type Number of members to be input 


fp Pointer indicating | File pointer 
FILE type 


Type size_t 
If size or nis 0: 0 
Return value) Normal If size and n are both nonzero: Number of successfully input members 


The fread function inputs n members whose size is specified by size, from the stream input/output 
file indicated by file pointer fp, into the storage area pointed to by ptr. The file position indicator 
for the file is advanced by the number of bytes input. 


The fread function returns the number of members successfully input, which is normally the same 
as the value of n. However, at end-of-file or if an error occurs, the number of members 
successfully input so far is returned, and so the return value will be less than n. The ferror and 
feof functions should be used to distinguish between end-of-file and error occurrence. 


Note 


If the value of size or n is zero, zero is returned as the return value and the contents of the storage 
area pointed to by ptr are unchanged. If an error occurs, or if only some of the members can be 
input, the file position indicator will be undefined. 
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7.11.32 fwrite Function 


Outputs data from a memory area to a stream input/output file. 


#include <stdio.h> 
const void *ptr; 
Calling size t size ; 
procedure |size_t n, ret ; 
FILE *fp ; 


ret=fwrite(ptr, size, n, 


Pointer indicating | Pointer to storage area holding 
const void type data to be output 
Parameters oe oe ae Number of | Number of bytes in one member _| in one member 
a | of members to be output 


Pointer indicating | File pointer 
FILE type 


[Type [Type | size_ t 
Return value Number of successfully output members 


The fwrite function inputs n members whose size is specified by size, from the storage area 


pointed to by ptr, to the stream input/output file indicated by file pointer fp. The file position 
indicator for the file is advanced by the number of bytes output. 


The fwrite function returns the number of members successfully output, which is normally the 
same as the value of n. However, if an error occurs, the number of members successfully output 
so far is returned, and so the return value will be less than n. 


Note 


If an error occurs, the file position indicator will be undefined. 
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7.11.33 fseek Function 


Function 


Shifts the current read/write position in a stream input/output file. 


#include <stdio.h> 
FILE *fp ; 
Calling long offset ; 
procedure int type, ret ; 


ret=fseek(fp, offset, type) ; 


: 
1 fp Pointer indicating File pointer 
FILE type 
Parameters offset long type Offset from position specified 
by type of offset 


int type Type of offset 


int 


Return value 


Abnormal | Nonzero 


The fseek function shifts the current read/write position in the stream input/output file indicated by 
file pointer fp, offset bytes from the position specified by the type of offset (type). 
The types of offset are shown in table 7.10. 


The fseek function normally returns zero, but returns nonzero in response to an invalid request. 


Table 7.10 Types of Offset 


Offset Type Meaning 


SEEK_SET Shifts to a position offset bytes from the beginning of the file. The value specified 
by offset must be zero or positive. 


SEEK_CUR Shifts to a position offset bytes from the current position in the file. The shift is 
toward the end of the file if the value specified by offset is positive, and toward 
the beginning of the file if negative. 


SEEK_END Shifts to a position offset bytes forward from end-of-file. The value specified by 
offset must be zero or negative. 


Note 


In the case of a text file, the type of offset must be SEEK_SET and offset must be zero or the 
value returned by the ftell function for that file. Note also that calling the fseek function cancels 
the effect of the ungetc function. 
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7.11.34  ftell Function 


Obtains the current read/write position in a stream input/output file. 


#include <stdio.h> 
FILE *fp ; 


ane long ret ; 


procedure 
ret= nae 


Parameters aia Pointer indicating FILE type File pointer 
2 


Return value! Normal 


Current file position indicator position (text file) 
Number of bytes from beginning of file to current position (binary file) 


| Abnormal_| 


The ftell function obtains the current read/write position in the stream input/output file indicated 
by file pointer fp. 


For a binary file, the ftell function returns the number of bytes from the beginning of the file to the 
current position. For a text file, it returns, as the file position indicator position, an 
implementation-defined value that can be used by the fseek function. 


Note 


If the ftell function is used twice for a text file, the difference in the return values will not 
represent the actual distance in the file. 
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7.11.35 rewind Function 


[Function | 


Shifts the current read/write position in a stream input/output file to _[fineton | 
Description | beginning of the file. 


#include <stdio.h> 
Calling FILE *fp ; 
procedure rewind (fp) ; 


[Ne [Name [Type CMeaing 
Parameters et 


| Pointer indicating FILE type File pointer 


Return value 


The rewind function shifts the current read/write position in the stream input/output file indicated 
by file pointer fp, to the beginning of the file. 


The rewind function clears the end-of-file indicator and error indicator for the file. 
Note 


Note that calling the rewind function cancels the effect of the ungetc function. 


7.11.36 clearerr Function 


Clears the error state of a stream input/output file. 


#include <stdio.h> 
Calling FILE *fp ; 
procedure co at 


Parameters ae Pointer indicating FILE type File pointer 


[Type | void 


Return value a 
Abnormal 


The clearerr function clears the error indicator and end-of-file indicator for the stream input/output 
file indicated by file pointer fp. 


Rev. 1.0, 09/98, page 284 of 476 
HITACHI 


7.11.37 feof Function 


Function 


Tests for the end of a stream input/output file. 


#include <stdio.h> 
FILE *fp ; 
int ret ; 


Calling 
procedure 
ret=feof(fp) ; 


[Ne [Name [Type [ering 
Parameters 


pt] Pointer indicating FILE type File pointer 


No. 
1 
ee End-of-file: Nonzero 
Otherwise: 0 
—— 


The feof function tests for the end of the stream input/output file indicated by file pointer fp. 


The feof function tests the end-of-file indicator for the specified stream input/output file, and if the 
indicator is set, returns nonzero to indicate that the file is at its end. If the end-of-file indicator is 
not set, the feof function returns zero to indicate that the file is not yet at its end. 
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7.11.38 ferror Function 


Function 


Tests for stream input/output file error state. 


#include <stdio.h> 
FILE *fp ; 
Int ret ; 


| Calling 
| procedure 
| ret=ferror (fp) 


[Re [Name [ype Maing 
| Parameters 


aka Pointer indicating FILE type File pointer 


R I N If file is in error state: Nonzero 
eturn value} Norma Otherwise: 0 


The ferror function tests whether the stream input/output file indicated by file pointer fp is in the 
error state. 


The ferror function tests the error indicator for the specified stream input/output file, and if the 
indicator is set, returns nonzero to indicate that the file is in the error state. If the error indicator is 
not set, the ferror function returns zero to indicate that the file is not in the error state. 
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7.11.39 perror Function 


perror Function 


_ Outputs an error message corresponding to the error number to the standard error 
Description | file (stderr). 


#include <stdio.h> 


Calling const char *s; 


rocedure 
P ae (s); 


Parameters a 


Pointer indicating Pointer to error message 
const char type 


[Type [Type —_| void 


Return value} Normal 


The perror function maps errno to the error message indicated by s, and outputs the message to the 
standard error file (stderr). 


If s is not a null pointer and the string pointed to by s is not the null character, the output format is 
as follows: the string pointed to by s followed by a colon and space, then the implementation- 
defined error message, and finally a new-line character. 
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7.12 <stdlib.h> 


Overview 


Defines standard functions for standard processing of C program. 


Definition Name List 


Definition name 


onexit_t 


div_t 


Idiv_t 


RAND_MAX 


atof 


atoi 
atol 
strtod 


strtol 


rand 


Type 


Macro name 


Macro name 


Macro name 


Macro name 


Function 


Function 
Function 


Function 


Function 


Function 


Description 


Indicates the return value type of the registered function for 
the onexit function and the return value type of the onexit 
function. 


Indicates the type of structure of the value returned by the div 
function. 


Indicates the type of structure of the value returned by the 
Idiv function. 


Indicates the maximum of pseudo-random integers 
generated by the rand function. 


Converts a number-representing string to a double type 
floating point number. 


Converts a decimal-representing string to an int type integer. 
Converts a decimal-representing string to a long type integer. 


Converts a number-representing string to a double type 
floating point number. 


Converts a number-representing string to a long type integer. 


Generates pseudo-random integers from 0 to RAND_MAX. 


srand 


calloc 


free 
malloc 
realloc 
abort 


Function 


Function 


Function 
Function 
Function 


Function 


Sets an initial value of the pseudo-random number series 
generated by the rand function. 


Allocates storage areas and clears all bits in the allocated 
storage areas to 0. 


Releases specified storage area. 
Allocates a storage area. 


Changes the size of storage area to a specified value. 


Abnormally terminates program. 


exit 


getenv 


Function 


Function 


Normally terminates program. 


References the definition of the name in the program-starting 


onexit 


Function 
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Definition name Type Description 


system Function Executes a specified string as an OS command. 

bsearch Function Performs binary search. 

qsort Function Performs sorting. 

abs Function Calculates the absolute value of an int type integer. 

div Function Carries out division of int type integers and obtains the 
quotient and remainder. 

labs Function Calculates the absolute value of a long type integer. 

Idiv Function Carries out division of long type integers and obtains the 


quotient and remainder. 
Definitions of the macro names in the list are implementation-defined. 


7.12.1 atof Function 


Description | Converts a number-representing string to a double type floating point number. 


#include <stdlib.h> 
Calling const char *nptr; 
procedure | double ret; 


ret=atof (nptr) ; 


Parameters 


1 nptr Pointer Pointer to a number-representing 
indicating const | string to be converted 
char type 


Return value Converted data as a double type floating point number 


Data is converted up to the first character that does not fit the floating point data type. 


Note 


The atof function sets no errno even if an error such as an overflow occurs. If an error occurs, the 
result will be undefined. When there are probabilities of a conversion error, use the strtod 
function. 
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7.12.2  atoi Function 


Description | Converts a decimal-representing string to an int type integer. 
#include <stdlib.h> 

Calling const char *nptr; 

procedure |int ret; 


ret=atoi (nptr) ; 


Parameters 


1 nptr Pointer Pointer to a number-representing 
indicating const | string to be converted 
char type 


Return value Converted data as an int type integer 


| Abnormal_| 


Data is converted up to the first character that does not fit the decimal data type. 
Note 


The atoi function sets no errno even if an error such as an overflow occurs. If an error occurs, the 
result will be undefined. When there are probabilities of a conversion error, use the strtol 
function. 
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7.12.3 atol Function 


Function 


Converts a decimal-representing string to a long type integer. 


#include <stdlib.h> 
Calling const char *nptr; 
procedure |long ret; 
ret=atol (nptr) ; 


Parameters 


1 nptr Pointer Pointer to a number-representing 
indicating const | string to be converted 
char type 


Return value Converted data as a long type integer 
| Abnormal | 


Data is converted up to the first character that does not fit the decimal data type. 
Note 


The atol function sets no errno even if an error such as an overflow occurs. If an error occurs, the 
result will be undefined. When there are probabilities of a conversion error, use the strtol 
function. 
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7.12.4  strtod Function 


Converts a number-representing string to a double type floating point number. 


#include <stdlib.h> 
. const char *nptr; 
Calling char **endptr; 
procedure double ret; 


ret=strtod(nptr, endptr) ; 


1 nptr Pointer Pointer to a number-representing 
indicating const | string to be converted 
Parameters char type 


2 endptr Pointer to a Pointer to the address containing a 
pointer pointer to the first character that 
indicating char | does not represent a floating point 
type number 


Type double 


If the string pointed by nptr is beginning with a character that does not 
represent a floating point number: 0 
Normal If the string pointed by nptr is beginning with a character that 
Return value represents a floating point number: converted data as a double type 


floating point number 


Abnormal _ | If the converted data overflows: HUGE_VAL with the same sign as 
that of the string to be converted 


If the converted data underflows: 0 


According to the C language specification rules, the strtod function converts data, from the first 
character or the decimal point up to the character immediately before the character that does not 
represent a floating point number, into a double type floating point number. However, if neither 
the exponent nor decimal point is found in the data to be converted, it is assumed that the decimal 
point comes next to the last numeral in the string. In the address pointed by endptr, this function 
sets up a pointer to the first character that does not consist a floating point number. If some 
characters that do not consist a floating point number come before numerals, the value of nptr is 
set in this address. If endptr is NULL, nothing is set in this address. 


Error Conditions 


If the converted result overflows or underflows, ERANGE is set for errno. 
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7.12.5 — strtol Function 


Description | Converts a number-representing string to a long type integer. 


#include <stdlib.h> 
long ret; 

const char *nptr; 
char **endptr; 
int base; 


Calling 
procedure 


a base) ; 


Nene Pointer indicating const | Pointer to a number-representing 
char type string to be converted 


Parameters endptr | Pointer to a pointer Pointer to the storage area 
indicating char type containing a pointer to the first 
character that does not represent 
an integer 


| 3 | base | int type Radix of conversion (0 or 2 to 36) 


[Type | long 


endptr, 


If the string pointed by nptr is beginning with a character that does not 
represent an integer: 0 

If the string pointed by nptr is beginning with a character that 
represents an integer: Converted data as a long type integer 


Abnormal | If the converted data overflows: LONG_MAX or LONG_MIN 
depending on the sign of the string to be converted 


The strtol function converts data, from the first numeral to the first character that does not 
represent an integer, into a long type integer. 


Return value| Normal 


In the address pointed by endptr, this function sets up another pointer to the first character that 
does not represent an integer. If some characters that do not represent an integer come before the 
first numeral, the value of nptr is set in this address. If endptr is NULL, nothing is set in this 
address. 


If the value of base is 0, C language specification rules are observed at conversion. If the value of 
base is 2 to 36, it indicates the radix of conversion, where a (or A) to z (or Z) in the string to be 
converted are corresponded to numbers 10 to 35. Ifa character that is not smaller than the base 
value is found in the string to be converted, conversion stops immediately. A 0 after a sign is 
ignored at conversion. Similarly, 0x (or 0X) at base 16 is ignored. 


Error Conditions 


If the converted result overflows, ERANGE is set for errno. 
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7.12.6 rand Function 


Function 


Generates pseudo-random integers from 0 to RAND_MAX. 


#include <stdlib.h> 


Calling int ret; 
procedure 


ret=rand( ); 


) 


Return value} Normal Pseudo-random integers 


7.12.7. srand Function 


— Sets an initial value of the pseudo-random number series generated by the rand 
Description function. 


#include <stdlib.h> 


Calling unsigned int seed; 


rocedure 
srand (seed) ; 


Parameters 1 unsigned int Initial value for pseudo-random 
type number series generation 


Return value} Normal 
Abnormal 


The srand function sets up an initial value for pseudo-random number series generation of the rand 
function. While pseudo-random number series generation by the rand function is ongoing, if the 
same initial value is set up again by the srand function, the same pseudo-random number series is 
repeated. 


Note 


If the rand function is called before the srand function, | is set as the initial value for the pseudo- 
random number generation. 
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7.12.8  calloc Function 


Allocates storage areas and clears all bits in the allocated storage areas to 0. 


#include <stdlib.h> 
size t nelem, elsize; 
void *ret; 


Calling 
procedure 


ret=calloc(nelem, elsize); 


arameters 


2 elsize size_t type Number of bytes occupied by a 
single element 
Pointer to void type 


Return value Starting address of allocated storage area 


The calloc function allocates as many storage areas as specified by nelem, in as many units of 
bytes as specified by elsize. The function also clears all the bits in the allocated storage area to 0. 


If storage allocation failed, or if either of the parameter is 0: NULL 
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7.12.9 free Function 


Function 


Releases specified storage area. 


#include <stdlib.h> 
Calling void *ptr; 
procedure 


free (ptr) ; 


ae a ee es 
Parameters 


Pointer Address of storage area to release 
indicating void 
type 


[Type void 


Return value ca 


The free function releases the storage area pointed by ptr, to enable reallocation for use. If ptr is 
NULL, the function carries out nothing. 


Note 


If the storage area attempted to release was not allocated by the calloc, malloc, or realloc function, 
or if the area has been already released by the free or realloc function, operation will be undefined. 
Operation result of referencing an already released storage area is also undefined. 


7.12.10 malloc Function 


Function 


Allocates storage area. 


#include <stdlib.h> 
size t size; 
void *ret; 


Calling 


procedure 
a oe 


Parameters a 


size size_t type Size in number of bytes of storage 
area to allocate 


Pointer to void type 


Return value Starting address of allocated storage area 


| Abnormal. If storage allocation failed, or if size is 0: NULL 


The malloc function allocates a storage area of a specified number of bytes by size. 
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7.12.11  realloc Function 


Function 
Changes the size of a storage area to a specified value. 


#include <stdlib.h> 
Calling size_t size; 
procedure |VOid *ptr, *ret; 


ret=realloc(ptr, size); 


1 ptr Pointer Starting address of storage area to 
Pp t indicating void | be changed 
arameters type 
size size_t type Size of storage area in number of 
bytes after the change 


[Type Pointer to void type 


Return value Starting address of size-changed storage area 
If storage area allocation failed, or if size is 0: NULL 


The realloc function changes the size of a storage area specified by ptr to the number of bytes 
specified by size. If the newly allocated storage area is smaller than the old one, the contents are 
left unchanged up to the size of the newly allocated area. 


Note 


If ptr is not a pointer to a storage area allocated by the calloc, malloc, or realloc function, or the 
pointer is pointing to an area that has already been released by the free or realloc function, 
operation will be undefined. 
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7.12.12 abort Function 


abort Function 


#include <stdlib.h> 
abort( ); 


Return value] Normal 
Abnormal 


The abort function abnormally terminates a program in which the function is executed. 


If SIGABRT is registered by the signal function, execution of the abort function is ignored. 
Note 


After the abort function is executed, the control is not returned to the program where the abort 
function has been called. When an output file is opened at abortion of a program, whether data 
left in stream buffer should be output to the output file, whether the opened file should be closed, 
and whether temporary files are deleted are implementation-defined. 
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7.12.13 exit Function 


Function 


Normally terminates program. 


#include <stdlib.h> 


Calling int status; 


procedure : 
exit (status) ; 


Return value 


The exit function sequentially performs three processes below: 


(1) Calls all the functions registered by the onexit function, in the reverse order of registration. 


(2) Flushes the contents of output buffer for all the open output files, then closes all the open files 
and deletes temporary files. 


(3) Returns control to the environment where the program was started. 
Note 


If the value of status is 0, the function returns control with normal termination state to the 
program-starting environment. If the value is other than 0, the function returns control with 
implementation-defined state to the program-starting environment. 
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7.12.14 getenv Function 


getenv Function 


Description | References the definition of the name in the program-starting environment. 


#include <stdlib.h> 
Calling const char *name; 
procedure | char *ret; 


ret=getenv (name) ; 


A 
Parameters 


name Pointer Pointer to the string that matches a 
indicating const | name to reference. 
char type 


[Type Pointer to char type 


If a name corresponding name is found: Pointer to the beginning of 
Return value| Normal the definition of that name 
If aname corresponding name is not found: NULL 


| Abnormal_| 


Definitions of names in the environment where program is started are collected in a list called the 
environment list, as shown below. 


name)=definition, 


name,=definition, 


name,=definition, 


The getenv function searches the environment list for a name that matches name, and returns the 
starting position (address) of the definition of the name. 
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7.12.15 onexit Function 


Function 


Registers a function to be called at the end of program. 


#include <stdlib.h> 
Calling onexit t (*func) ( ); 


procedure onexit t ret; 


ret=onexit (func) ; 


Parameters 3 


func Pointer to a Name of the function to be called 
function at program termination 
Return vee a Value not equivalent to NULL 


Value equivalent to NULL 


Note 


If the same function is registered twice or more, operation will be undefined. 


7.12.16 system Function 


system Function 
Description | Executes a specified string as an OS command. 


#include <stdlib.h> 
Calling const char *string; 
procedure |int ret; 


ret=system(string) ; 


Se ee oe 
Parameters string Pointer Pointer to the name of the 
indicating const | command to be executed 
char type 
a a 
Return value| Normal _| Implementation-defined value 


If string is NULL: 0 


The system function uses the string specified by string for an operating system command name, 
and executes the command by a method determined by the compiler. 
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7.12.17  bsearch Function 


fpeearey «CS 
Performs binary search. 


#include <stdlib.h> 
const void *key, *base; 

Calling size_t nmemb, size; 

procedure int (*compar) (const void *, const void *) 
void *ret; 


ret=bsearch(key, base, nmemb, size, — 


Pointer indicating const | Pointer to data to search for 
void type 


Pointer indicating const | Pointer to a table to search 
void type 


Parameters 
Number | Number of members to search for | members to search for 


size size_t type Number of amber of members e579 of a member to 
search for 
compar | Pointer to a function Pointer to a function that performs 
that returns an int type | comparison 
value 


[Type | Pointer to void type 


If a matching member is found: pointer to the matching member 


Return value) Normal If no matching member is found: NULL 


The bsearch function searches the table specified by base for a member that matches the data 
specified by key, by binary search method. The function that performs comparison should receive 
pointers p1 (first parameter) and p2 (second parameter) to two data to compare, and return the 
result complying with specifications below. 


If *pl<*p2, return a negative value. 
If *pl==*p2, return 0. 

If *p1>*p2, return a positive value. 
Note 


Members to search must be placed in the ascending order. 
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7.12.18 qsort Function 


Performs sorting. 


#include <stdlib.h> 

const void *base; 

size_t nmemb, size; 

int (*compar) (const void *, const void *); 


Calling 
procedure 


ier | nmemb, size, compar) ; 


rene | indicating const | Pointer to the sort target table 
void type 


size size_t type Number es bytes of a member to 
sort 
compar | Pointer to a function Pointer to a function to perform 
that returns int type comparison 
value 


Return value} Normal 


| Abnormal. | 


The qsort function sorts out data on the table specified by base. The data arrangement order is 
specified by the pointer to a function to perform comparison. This comparison function should 
receive pointers p1 (first parameter) and p2 (second parameter) to two data to compare, and return 
the result complying with specifications below. 


If *pl<*p2, return a negative value. 
If *pl==*p2, return 0. 


If *p1>*p2, return a positive value. 
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7.12.19 abs Function 


Calculates the absolute value of an int type integer. 


: #include <stdlib.h> 
Calling int i, ret; 
procedure 


ret=abs ( 


Parameters <a 


int type Integer to calculate the absolute 
value of 
Type 


Return value Absolute value of i 


Note 


If the result cannot be expressed as an int type integer, operation will be undefined. 


7.12.20 div Function 


iv 
Carries out division of int type integers and obtains the quotient and remainder. 


#include <stdlib.h> 
Calling int numer, denom; 


procedure |div_t ret; 


ret=div (numer, denom) ; 


a 


Return value Quotient and remainder of division of numer by denom 
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7.12.21 labs Function 


Function 


Calculates the absolute value of a long type integer. 


#include <stdlib.h> 
Calling long j; 
procedure | long ret; 


ret=labs(j); 


3) 
Parameters 


1 j long type Integer to calculate the absolute 
value of 


long 
Return value Absolute value of j 


Note 


If the result cannot be expressed as an long type integer, operation will be undefined. 


7.12.22 Idiv Function 


Carries out division of long type integers and obtains the quotient and remainder. 


#include <stdlib.h> 
Calling long numer, denom; 
procedure |1ldiv_t ret; 


ret=ldiv(numer, denom) ; 


on pe 


Type Idiv_t 
Return value Quotient and remainder of division of numer by denom 
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7.13 <string.h> 


Overview 


Defines functions for manipulating character arrays. 


Definition Names 


Definition Name 


memcpy 


strcpy 


strncpy 


strcat 


strncat 


memcmp 
strcmp 
strncmp 


memchr 


strchr 


strcspn 


strpbrk 


strrchr 


strspn 


strstr 


strtok 


memset 
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Type 
Function 


Function 


Function 


Function 


Function 


Function 
Function 
Function 


Function 


Function 


Function 


Function 


Function 


Function 


Function 


Function 


Function 


Description 


Copies contents of a source storage area of a specified 
length to a destination storage area. 


Copies contents of a source string including the null 
character to a destination storage area. 


Copies a source string of a specified length to a destination 
storage area. 


Concatenates a string after another string. 


Concatenates a string of a specified length after another 
string. 


Compares two storage areas specified. 
Compares two strings specified. 
Compares two strings specified for a specified length. 


Searches a specified storage area for the first occurrence of 
a specified character. 


Searches a specified string for the first occurrence of a 
specified character. 


Checks a specified string from the beginning and counts the 
number of consecutive characters at the beginning that are 
not included in another string specified. 


Searches a specified string for the first occurrence of any 
character that is included in another string specified. 


Searches a specified string for the last occurrence of a 
specified character. 


Checks a specified string from the beginning and counts the 
number of consecutive characters at the beginning that are 
included in another string specified. 


Searches a specified string for the first occurrence of another 
string specified. 


Divides a specified string into some tokens. 


Sets a specified character for a specified number of times at 
the beginning of a specified storage area. 
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Definition Name Type Description 
strerror Function Sets error messages. 


strlen Function Calculates the length of a string. 


When using functions defined in this standard include file, note the following. 


(1) When a string is to be copied, if the destination area is smaller than the source area, operation 
will be undefined. 
Example 
char a[]="abc"; 


char b[3]; 


strcpy (b, a); 


In the above example, size of array a (including the null character) is 4 bytes. Copying by 
strcpy rewrites data beyond the boundary of array b. 


Betone cory ATEr copy 


EEE PELE 
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(2) When a string is to be copied, if the source area overlaps the destination area, operation will be 
undefined. 


Example 


int a[ J="a"; 


strepy(&a[1], a); 


In the above example, before the null character of the source is read, "a" is written on the null 
character, then the subsequent data after the source string is rewritten in succession. 


Before corny 


Salt] 
Subsequent data is copied in successicr. 
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7.13.1 memcpy Function 


memcpy Function 


ae Copies contents of a copy source storage area of a specified length to a 
Description | destination storage area. 


#include <string.h> 
void *ret, *sl1; 
const void *s2; 
size tn; 


Calling 
procedure 


ret=memcpy(s1, s2, n); 


n 


1 s1 Pointer indicating void | Pointer to destination storage area 
type 
Parameters ——— ; 
2 $2 Pointer indicating const | Pointer to source storage area 
void type 


[3 | _[szetype [Number ofcharacersto copy 
Pointer to void type 
Return value s1 value 
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7.13.2 strepy Function 


strcpy [Function | 


D Copies contents of a source string including the null character to a __urcion_| 
escription | storage area. 


#include <string.h> 
Calling char *s1, *ret; 
procedure const char *s2; 


ret=strcpy(s1, 


a 


Pointer indicating char | Pointer to destination storage area 
Parameters type 

Pointer indicating const | Pointer to source string 

char type 


[Type [Type —_| Pointer to char type 


Return value} Normal s1 value 
Abnormal 
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7.13.3 strncpy Function 


strncpy Function 


Copies a source string of a specified length to a destination storage area. 


#include <string.h> 
char *sl, *ret; 
const char *s2; 
size tn; 


Calling 
procedure 


ret=strncpy (s 


Pointer indicating char | Pointer to destination storage area 
type 
Parameters 
Pointer indicating const | Pointer to source string 
char type 


Pointer to char type 


Return value| Normal $1 value 


| Abnormal | 


The strncpy function copies a string pointed by s2 for up to n characters to a storage area pointed 
by sl. If the length of the string specified by s2 is shorter than n characters, the function elongates 
the string to the length by padding with null characters. 


Note 


If the length of the string specified by s2 is longer than n characters, the copied string in s1 storage 
area ends with a character other than the null character. 
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7.13.4  strcat Function 


Concatenates a string after another string. 


#include <string.h> 
char *sl, *ret; 
const char *s2; 


Calling 
procedure 
| sl, s2); 


| Name | | Type | = Meaning 


mee indicating char | Pointer to the string after which 
Parameters type another string is added 


Pointer indicating const | Pointer to the string to add after the 
char type other string 


Pointer to char type 
Return value s1 value 


The strcat function copies the string specified by s2 at the end of another string specified by s1. 
The null character indicating the end of the s2 string is also copied. The null character at the end 
of the s1 string is deleted. 
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7.13.5 strncat Function 


Concatenates a string of a specified length after another string. 


#include <string.h> 
char *sl, *ret; 
const char *s2; 
size tn; 


Calling 
procedure 


ret=strncat(sl, s2, 


n); 


1 s1 Pointer indicating char | Pointer to the string after which 
type another string is added 
Parameters 2 s2 Pointer indicating const | Pointer to the string to add after the 
char type other string 
3 n size_t type Number of characters to 
concatenate 


Pointer to char type 
Return value $1 value 


The strncat function copies up to n characters from the beginning of the string specified by s2 at 
the end of another string specified by sl. The null character at the end of the s1 string is replaced 
by the first character of the s2 string. A null character is added to the end of the concatenated 
string. 
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7.13.6 memcmp Function 


Function 
Description | Compares two storage areas specified. 


#include <string.h> 
const void *sl, *s2; 
size t n; 
int ret; 


Calling 
procedure 


ret=memcmp (s1, Ds 


Pointer indicating const | Pointer to the reference storage 
void type area to compare with 
Parameters 


Pointer indicating const | Pointer to the storage area to 
void type compare to the reference 


ee size_t type Number of characters to compare 


‘Type | int 
If storage area pointed by s1 > storage area pointed by s2: positive 
value 
Return value} Normal If storage area pointed by s1 == storage area pointed by s2: 0 
If storage area pointed by s1 < storage area pointed by s2: negative 
value 
aenomal [= SC“~“S*s*s~“‘s~‘“‘~*~* 


The memcmp function compares the contents of the first n characters in the storage areas pointed 
by sl and s2. The rule of comparison are implementation-defined. 
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7.13.7 | stremp Function 


Description | Compares two strings specified. 


#include <string.h> 
Calling const char *sl, *s2; 
procedure |int ret; 


ae (sl, s2); 


Pointer indicating const | Pointer to the reference string to 
Parameters char type compare with 


Pointer indicating const | Pointer to the string to compare to 
char type the reference 


Type | 


If string pointed by s1 > string pointed by s2: positive value 
Return value} Normal If string pointed by s1 == string pointed by s2: 0 


If string pointed by s1 < string pointed by s2: negative value 
| Abnormal. | 


The stremp function compares the contents of the strings pointed by sl and s2, and sets up the 
comparison result as a return value. The rule of comparison are implementation-defined. 
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7.13.8 | strncmp Function 


Function 
Compares two strings specified for a specified length. 


#include <string.h> 
const char *sl, *s2; 
Calling size tn; 
procedure int ret; 


ret=strncmp(sl, s2, n); 


Name Type Meaning 
2 ee a ae a 


Pointer indicating const | Pointer to the reference string to 
char type compare with 


Parameters 2 s2 Pointer indicating const | Pointer to the string to compare to 
char type the reference 
size_t type Maximum number of characters to 
compare 


Five [in 


If string pointed by s1 > string pointed by s2: positive value 
Return value} Normal If string pointed by s1 == string pointed by s2: 0 
If string pointed by s1 < string pointed by s2: negative value 


The strncmp function compares the contents of the strings pointed by s1 and s2, for up ton 
characters. The rule of comparison are implementation-defined. 
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7.13.9  memchr Function 


memchr Function 
Description | Searches a specified storage area for the first occurrence of a specified character. 


#include <string.h> 
const void *s; 
Calling int <i; 
procedure size_t n; 
void *ret; 


ret= a a, 


iw) 7 


vere indicating const | Pointer to the storage area to 
Parameters void type search 


ae int type Character to search for 


[Type [Type _| Pointer to void type 


Send If the objective character is found: Pointer to the found character 
Return value} Normal If the objective character is not found: NULL 


| Abnormal_| 


The memchr function searches the storage area specified by s from the beginning up to n 
characters, looking for the first occurrence of the character specified as c. If the c character is 
found, the function returns the pointer to the address of that character. 


Rev. 1.0, 09/98, page 317 of 476 
HITACHI 


7.13.10 strchr Function 


strchr Function 


Searches a specified string for the first occurrence of a specified character. 


#include <string.h> 
const char *s; 
Calling int c; 
procedure | Ghar *ret; 


ret=strchr(s, c); 


1 
Parameters ZZ 


Pointer indicating const | Pointer to the string to search 
char type 


Ss 
int type Character to search for 


Pointer to char type 
If the objective character is found: Pointer to the found character 
Return value| Normal If the objective character is not found: NULL 


The strchr function searches the string specified by s looking for the first occurrence of the 
character specified as c. If the c character is found, the function returns the pointer to the address 
of that character. 


Note 


The null character at the end of the s string is included in the search objective. 
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7.13.11  strespn Function 


Checks a specified string from the beginning and counts the number of 
Description | consecutive characters at the beginning that are not included in another string 
specified. 


#include <string.h> 
Calling const char *sl, *s2; 
procedure size t ret; 


ret=strcspn(sl, s2); 


Parameters 


Number of characters at the beginning of the s1 string that are not 
Return value| Normal included in the s2 string 


The strcspn function checks from the beginning of the string specified by s1, and counts the 
number of consecutive characters that are not included in another string specified by s2, and 
returns that length. 


Note 


The null character at the end of the s2 string is not taken as a part of the s2 string. 
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7.13.12  strpbrk Function 


[Function | 


Searches a specified string for the first occurrence of any character _[Fencton is included 
Description | i, another string specified. 


#include <string.h> 
Calling const char *sl, *s2; 


procedure |Char *ret; 
ret= ae ; 


Nene | indicating const | Pointer to the string to search 
Parameters char type 
Pointer indicating const | Pointer to the string that indicates 
char type the characters to search s1 for 
Pointer to char type 


If the objective character is found: Pointer to the found character 
If the objective character is not found: NULL 


Return value| Normal 
Abnormal 


The strpbrk function searches the string specified by s1 looking for the first occurrence of any 
character included in the string specified by s2. If the searched character is found, the function 
returns the pointer to the address of the first occurrence. 
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7.13.13 strrchr Function 


strrchr Function 


Searches a specified string for the last occurrence of a specified character. 


#include <string.h> 
const char *s; 

int c; 

char *ret; 


Calling 
procedure 


ret=strrchr(s, 


Pointer indicating const | Pointer to the string to search 
Parameters char type 


| 2 | « | int type Character to search for 


[Type Pointer to char type 


If the objective character is found: Pointer to the found character 
Return value) Normal If the objective character is not found: NULL 


| Abnormal _| 


The strrchr function searches the string specified by s looking for the last occurrence of the 
character specified as c. If the c character is found, the function returns the pointer to the address 
of the last occurrence of that character. 


Note 


The null character at the end of the s string is included in the search objective. 
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7.13.14  strspn Function 


Checks a specified string from the beginning and counts the number of 
Description | consecutive characters at the beginning that are included in another string 
specified. 
#include <string.h> 
Calling const char *sl, *s2; 
procedure size t net; 


ret=strspn(sl, s2) 


a 


Pointer indicating const | Pointer to the string to check 
Parameters char type 
2 s2 Pointer indicating const | Pointer to the string used to check 
char type $1 


Return value Number of consecutive s2-specified characters at the beginning of s1 
|Abnormal_| 


The strspn function checks from the beginning of the string specified by s1, and counts the number 
of consecutive characters that are included in another string specified by s2, and returns that 
length. 
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7.13.15 strstr Function 


Searches a specified string for the first occurrence of another string specified. 


#include <string.h> 
Calling const char *sl, *s2; 


procedure | Char *ret; 


ret=strstr ( 


Pointer indicating const | Pointer to the string to search 
Parameters char type 


Pointer indicating const | Pointer to the string to search for 
char type 


Pointer to char type 


If the objective string is found: Pointer to the found string 


Return value| Normal —_| if the objective string is not found: NULL 


The strstr function searches the string specified by s1 looking for the first occurrence of another 
string specified by s2, and returns the pointer to the first occurrence. 
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7.13.16 strtok Function 


Divides a specified string into some tokens. 


#include <string.h> 
Calling char *si, *ret; 
procedure const char *s2; 


ret=strtok(sl, s2); 


1 s1 Pointer indicating char | Pointer to the string to divide into 
Parameters type some tokens 
2 s2 Pointer indicating const | Pointer to the string consisting of 
char type string dividing characters 


Pointer to char type 


If division into tokens is successful: Pointer to the first token divided 
If division into tokens is unsuccessful: NULL 


| [Abnormal | — 


The strtok function should be repeatedly called to divide a string. 


Return value} Normal 


(1) First call 


The string pointed by s1 is divided at a character included in the string pointed by s2. Ifa 
token has been separated, the function returns a pointer to the beginning of that token. 
Otherwise, the function returns NULL. 


(2) Second and subsequent calls 


Starting from the next character to the token separated before, the function repeats division at a 
character included in the string pointed by s2. If a token has been separated, the function 
returns a pointer to the beginning of that token. Otherwise, the function returns NULL. 


At the second and subsequent calls, specify NULL for the first parameter. 


The string pointed by s2 can be changed at each call. The null character is added to the end of 
a separated token. 
An example of use of the strtok function is shown below. 
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Example 


1 #include <string.h> 

2 static char sl[ ]="a@b, @c/@d"; 

3 char *ret; 

4 

5 ret = strtok(sil, "@l"); 

6 ret = strtok(NULL, ",@"); 

7 ret = strtok(NULL, "/@") ; 

8 ret = strtok(NULL, "@"); 
Explanation 


The above example program uses the strtok function to divide string "a@b, @c/@d" into tokens a, 
b, c, and d. 


The second line specifies string "a@b, @c/@d" as an initial value for string s1. 


The fifth line calls the strtok function to divide tokens using "@" as the delimiter. As a result, a 
pointer to character "a" is returned, and the null character is embedded at "@," the first delimiter 
after character "a." Thus string "a" has been separated. 


Specify NULL for the first argument to consecutively separate tokens from the same string, and 
repeat calling the strtok function. 


Consequently, the function separates strings "b," "c," and "d." 
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7.13.17 memset Function 


[Function | 


Sets a specified character for a specified number of times at the beginning Fonction a 
Description | <necified storage area. 


#include <string.h> 
void *s, *ret; 
Calling int ¢; 
procedure size t n; 


ret=memset ( 


Name Type Meaning 
a 


Pointer indicating void | Pointer to storage area to set 
Parameters type characters in 


int type Character to be set 
size_t type Number of characters to be set 


Type Pointer to void type 


Return value} Normal Value of s 


The memset function sets the character specified by c for a number of times specified by n to the 
storage area specified by s. 
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7.13.18 strerror Function 


Description | Returns an error message corresponding to a specified error number. 


#include <string.h> 
Calling char *ret; 
procedure |int s; 


ret=strerror(s) ; 


Parameters 
Pointer to char type 


Pointer to the error message (string) corresponding to the specified 
error number 


Return value} Normal 


The strerror function receives an error number specified by s and returns an error message 
corresponding to the number. Contents of error messages are implementation-defined. 


Note 


If the returned error message is modified, operation will be undefined. 
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7.13.19 strlen Function 


Calculates the length of a string. 


#include <string.h> 
Calling const char *s; 
procedure |Size_t ret; 


ret=strlen(s); 


Parameters 


1 Ss Pointer Pointer to the string to check the 
indicating const | length of 
char type 


Return value Number of characters of the string 


| Abnormal | 


Note 


The null character at the end of the s string is excluded from the string length. 
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7.14 <time.h> 
Overview 
Defines time-related functions. 


Definition Names 


Definition name Type 


CLK_TCK Macro name 
clock_t Macro name 
time_t Macro name 
struct tm Macro name 
clock Function 
difftime Function 
time Function 
asctim Function 
ctime Function 
gmtime Function 
localtime Function 


Description 


Indicates processor time used per second. This macro is 
used to convert return value from the clock function into 
seconds. 


Indicates the type of processor service time representation. 
Indicates the type of calendar time representation. 

Indicates the tag name of a structure to store particular time. 
Determines processor time used until the present time. 
Calculates the difference between two calendar times. 
Determines current calendar time. 


Converts particular time represented by a specified structure 
into string type. 


Converts specified calendar time into string type local time. 


Converts specified calendar time into particular Greenwich 
mean time (GMT). 


Converts specified calendar time into particular local time. 


Macro names above are all implementation-defined. 


Times used by the definition functions in this standard include file are explained below. 


(1) Calendar time: Calendar time consisting of date and time 

(2) Local time: Time for a specific time zone 

(3) Seasonal time: Temporarily modified time 

(4) Particular time: Necessary elements to express calendar time (second, minute, hour, day, 


month, year, day of the week, cumulative number of days, use of 
seasonal time) 
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7.14.1 clock Function 


Description | Determines processor time used until the present time. 


#include <time.h> 


Calling clock_t ret; 
procedure 


ret=clock( ); 


coataieg Od ee fe 
Parameters = | 


No. 
Processor service time from an point of time implementation-defined, 
ROturI Wale) Mrinal to the current time. 


If the processor service time is invalid: —1 


The clock function calculates processor service time from an implementation-defined point of time 
up to the current time, and returns the result. 


If the return value is to be in seconds, divide the return value by CLKTCK. 


7.14.2  difftime Function 


difftime Function 
Calculates the difference between two calendar times. 


#include <time.h> 
Calling time _t timel, time2; 
procedure double ret : 
ret=difftime(timel, time2); 


1 time time_t type Reference calendar time to 
compare with 
2 


Parameters 
time2 time_t type Calendar time to compare to the 
reference time 


Type double 
Return value Difference between two calendar times 


The difftime function receives two calendar times time] and time2, calculates the value of (timel- 


time2) in seconds, and returns the result. 
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7.14.3 time Function 


Description | Determines current calendar time. 


#include <time.h> 
Calling time t *timer, ret; 


procedure ret=time (timer) ; 


a a 
Parameters 


timer Pointer Pointer to the storage area where 
indicating time_t} current calendar time is set 
type 


Return value Current calendar time 
| Abnormal. | lf the calendar time is invalid: —1 


The time function determines current calendar time by implementation-defined method, and 
returns the result. If timer is not NULL, the same value as the return value is set in the storage 
area pointed by timer. 
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7.14.4  asctime Function 


Converts particular time represented by a specified structure into string type. 


#include <time.h> 
Calling char *xet; 
procedure const struct tm *timeptr; 


ret=asctime (timeptr) ; 


a a 
Parameters 


timeptr Pointer Particular time to be converted into 
indicating const | string data 
struct tm type 


[Type | [Type _| Pointer to char type 


Pointer to the string that has been converted from the broken-time 
Return value| Normal pointed by timeptr 


| Abnormal_| 


The asctime function converts particular time specified by timeptr into a string data in the format 
below. 


"day-of-the-week month day hour:minute:second year\n\0" into string type. 
Example 


"Mon Mar 01 16:54:10 1987\n\0" 
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7.14.5  ctime Function 


Function 


Converts specified calendar time into string type local time. 


#include <time.h> 
Calling const time_t *timer; 
procedure | Char *ret; 


ret=ctime (timer) ; 


A 
Parameters 


timer Pointer indicating const | Calendar time to be converted into 
time_t type string type local time 


Type Pointer to char type 


Pointer to the string type local time that has been converted from the 
Return value} Normal : ; 


calendar time pointed by timer 


Abnormal 


For the format of the converted string, see section 7.14.4, asctime Function. 


7.14.6 gmtime Function 


Converts specified calendar time into particular Greenwich mean time (GMT). 


#include <time.h> 
Calling const time_t *timer; 
procedure SEXUCE. Em “REE; 


ret=gmtime (timer) ; 


ee ee eae 
Parameters 


timer Pointer indicating const | Calendar time to convert into 
time_t type particular time 
Pointer to the structure defined by struct tm 
Return value Particular GMT corresponding to timer 


If GMT is invalid: NULL 
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7.14.7 localtime Function 


Converts specified calendar time into particular local time. 


#include <time.h> 
Calling const time t *timer; 
procedure struct tm *ret; 


ret=localtime (timer) 


a 
Parameters 


timer Pointer to const time_t | Calendar time to convert into 
particular local time 


[Type | Pointer to the structure defined by struct tm 
Return oo Particular local time corresponding to timer 
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Section 8 DSP Library 


8.1 Overview 


The shdsplib.lib is a digital signal processing (DSP) library developed for use with the SH-DSP. 
This library includes standard DSP functions, so various DSP operations can be performed by 
using a single function or using several functions in sequence. 


This library includes the following functions. 


e Fast Fourier Transforms 

e Window Functions 

e Filters 

e Convolution and Correlation 


e Miscellaneous 
These are re-entrant library functions except for the fast Fourier transforms and filters. 


When using this library, include ensigdsp.h in the program. In addition, when using a filter 
function from the library, include filt_ws.h. 


When calling the library, a return value, EDSP_OK is returned if a function is correctly 
terminated, and EDSP_BAD_ARG or EDSP_NO_HEAP is returned if a function is not correctly 
terminated. For details on the return value, refer to the description of each function. 


8.2 Data Formats 


This library regards data as a signed 16-bit fixed-point number. The signed 16-bit fixed-point 
number has a data format where the decimal point is fixed at the right of the most significant bit 
(MSB) as shown in figure 8.1(a). The signed 16-bit fixed-point number can represent values in 
the range from -1 to 1-2"'°. The library accepts data with a short-type data format. Therefore, it is 
necessary to represent data as signed 16-bit fixed-point number when using this library in a C/C++ 
program. 


For example, +0.5 is H'4000 when represented with signed 16-bit fixed-point number. Therefore, 
the short-type real argument sent to the library function is H'4000. 


For the operation within the library, signed 32-bit fixed-point number and signed 40-bit fixed- 
point number are also used. The data format of the signed 32-bit fixed-point number is shown in 
Figure 8.1(b). Values in the range from -1 to 1-27! can be represented. As shown in Figure 8.1(c), 
signed 40-bit fixed-point number has a data format with eight guard bits. Values in the range from 
-2° to 2°-2°! can be represented. 


Rev. 1.0, 09/98, page 335 of 476 


HITACHI 


The product of signed 16-bit fixed-point number is stored as signed 32-bit fixed-point number. An 
overflow will occur only if H'8000 is multiplied by H'8000 for fixed-point multiplication by using 
a DSP instruction. The least significant bit (LSB) of the product is always 0. To use the product 
for the next operation, the upper 16 bits are converted to signed 16-bit fixed-point number. At that 
time, underflow will occur, and accuracy will be lowered. 


For multiply-and-accumulate operation, the sum is stored in signed 40-bit fixed-point number. Be 
careful to prevent an overflow from occurring during addition. If an overflow occurs during the 
operation, the result will be incorrect. To avoid an overflow, a scaling of the coefficient and input 
data must be performed. This library incorporates a scaling function. For details on scaling, refer 
to the description of each function. 


fa) Signed 16-bit fixed-point number (-1 to 1-219) 


3 


fb) Signed Se-bit fixed-point nurniber (1 to 1-277) 


Guard bits 
fc) Signed 40-bit fixed-point number (-2* to 22-277) 


5: Signbit 
wh: Decirnal point 


Figure 8.1 Data Format 
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8.3 


This library function is optimized for fast execution on the SH-DSP. To use the library efficiently, 
the following two recommendations should be obeyed whenever possible when defining the 


e he program code segment should be located in memory that supports single cycle 32-bit 
reads 


e he data segment should be located in memory that supports single cycle 16 (or 32) bit reads 
and writes. 


and data. If other memory must be used, the recommendations above should be followed 
whenever possible. 
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Fast Fourier Transforms 


8.4.1 


Contents: 


FftReal 


IfftComplex 


FftInReal 


IfftInComplex 


LogMagnitude 
InitFft 


FreeFft 


Compute not-in-place, complex FFT. 


Compute not-in-place, complex inverse FFT. 
Compute not-in-place, real inverse FFT. 


Compute in-place, complex FFT. 


Compute in-place, complex inverse FFT. 


Compute in-place, real inverse FFT. 


ut to log magnitude format. 


Release FFT lookup table memory. 


For details on not-in-place and in-place, refer to the description " "in section 


These functions calculate 
defined scaling. The forward Fourier transform is defined by: 


H 
at ae er Opt «ye 


n=0 


where s is the number of stages where scaling is performed and N is the number of data. 


The inverse Fourier transform is defined by: 


H : 
W=2* F earl.» 


n=O 


For details on scaling, refer to the description "Scaling" in section 8.4.1, Overview. 
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Complex Array Format: 


In FFT and IFFT routines, complex data are stored using two arrays: the real part of data in X 
memory and the imaginary part of data in Y memory. However, the locations of real FFT output 
data and real IFFT input data differ. Assuming the arrays store real and imaginary parts as x and y 
respectively, element x[0] contains the real component of the DC component of the signal and y[0] 
contains the real component of the F,/2 frequency (both DC and F,/2 components are real, and 
their imaginary components are zero). 


Real Array Format: 
Real data can be specified in three possible formats: 


e The data is represented in a single array, located in any memory block. 
e The data is represented in a single array, located in X memory. 


e The data is split between two arrays, each of size N/2 The first half of the data is stored in the 
X memory; the second half is stored in the Y memory. 


FftReal uses the first representation for the real data. IfftReal, FftInReal and IfftInReal allow either 
the second or third representation. 


Scaling: 


In an FFT, the signal power doubles at each natural radix-2 stage; the peak signal amplitude can 
also double. This doubling can cause arithmetic overflow when transforming a high power signal, 
but can be prevented by a division by two at each radix-2 stage (this is called scaling). However, 
excessive halving of the signal will add unnecessary quantization noise. 


The optimum balance among overflow, quantization noise, and scaling depends highly on the 
characteristics of the input signal. When a peak of a signal spectrum is very large, for example, the 
maximum scaling will be required to avoid overflow, whereas an impulse signal will require very 
little scaling. 


The safest approach is to halve the signal amplitude at every radix-2 stage. As long as each 
complex input data is scaled to have power less than 2°’, this approach guarantees that overflow 
will not occur. This library allows finer control of scaling, with scaling selectable individually for 
each radix-2 stage. Careful selection of this scaling allows the combined effects of overflow and 
quantization to be minimized. 


To allow specification of the required approach each FFT function has a scale parameter. The scale 
is interpreted starting with the least significant bit, with one bit corresponding to each radix-2 
stage. A division by two is performed at all radix-2 stages whose corresponding scale bit has been 
set to 1. 
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The FFT implementation used in this library makes use of the radix-4 stages to improve execution 
speed. The scale is interpreted starting with the least significant bit, with two bits corresponding to 
each radix-4 stage. If either is set to 1, a division by two is performed; if both are set to 1, a 
division by four is performed. This gives the same overall scaling as if two radix-2 stages replaced 
each radix-4 stage, with minor differences in the quantization noise. 


For example: 


e scale = H'FFFFFFFF (or size-1) specifies halving on every radix-2 stage, with a guarantee that 
no overflow will occur if the input data all have power less than 2°°. 


e scale = H'55555555 specifies halving on alternate radix-2 FFT stages. 


e scale = 0 specifies no scaling. 


EFFTALLSCALE (H'FFFFFFFF), EFFTMIDSCALE (H'55555555) and EFFTNOSCALE (0), 
defined in ensigdsp.h, can be used to provide these values. 


FFT Structure: 


This library has two types of FFT structures: not-in-place FFT and in-place FFT. When a not-in- 
place FFT structure is used, input data is fetched from the RAM, FFT is executed, and output data 
is stored in another area of the RAM specified by the user. When an in-place FFT structure is 
used, input data is fetched from the RAM, FFT is executed, and output data is stored in the same 
area of the RAM. When an in-place FFT structure is used, the used memory space can be reduced 
but the FFT execution time increases. Use not-in-place FFT to use the same input data in other 
functions. Use in-place FFT to reduce the memory space required. 
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8.4.2 FftComplex 


Definition: 
int FftComplex (short op_x[ ], short op_y[ ], const short ip_x[ ], const short ip_y[ ], 
long size, long scale) 
Arguments: 
op_x[ ] real part of output data 
op_y[ ] imaginary part of output data 
ip_x{ ] real part of input data 
ip_y[ ] imaginary part of input data 
size size of FFT 
scale scaling specification 


Returns: int 
EDSP_OK success 
EDSP_BAD_ARG size <4 
size not a power of 2 
size > max_fft_size 
Description: 


This routine calculates a complex Fast Fourier Transform. The calculation is not-in-place, so the 
input and output arrays must not overlap. 


Notes: 


e The storage of complex data arrays is described in "Complex Array Format" in section 8.4.1, 
Overview. 


e Before calling this routine the lookup table and max_fft_size should be initialized by calling 
InitF ft. 


e Scaling specification is described in "Scaling" in section 8.4.1, Overview. 
e Only the bottom log) (size) bits of scale are used. 


e This routine is not re-entrant. 
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8.4.3 FftReal 


Definition: 

int FftReal (short op_x[ ], short op_y[ ], const short ip[ ], long size, long scale) 
Arguments: 

op_x[ ] real part of positive output data 

op_y[ ] imaginary part of positive output data 

ip[ ] real input data 

size size of FFT 

scale scaling specification 


Returns: int 
EDSP_OK success 


EDSP_BAD_ARG  size<8 
size not a power of 2 
size > max_fft_size 


Description: 
This routine calculates a real Fast Fourier Transform. 


On returning, op_x and op_y contain (size/2) positive output data only. The negative data are 
simply the complex conjugate of the positive data. Since the output data values at both 0 and F,/2 
are real, the F,/2 value is placed in op_y[0]. 


The calculation is not-in-place, so the input and output arrays must not overlap. 
Notes: 


e Storage of complex and real data arrays is described in "Complex Array Format" and "Real 
Array Format" in section 8.4.1, Overviw. 


e Before calling this routine the lookup table and max_fft_size should be initialized by calling 
InitF ft. 


e Scaling specification is described in "Scaling" in section 8.4.1, Overview. 
e Only the bottom log (size) bits of scale are used. 


e This routine is not re-entrant. 
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8.4.4 IfftComplex 


Definition: 
int IfftComplex (short op_x[ ], short op_y[ ], const short ip_x[ ], const short ip_y[ ], 
long size, long scale) 
Arguments: 
op_x{ ] real part of output data 
op_y[ ] imaginary part of output data 
ip_x[ ] real part of input data 
ip_y[ | imaginary part of input data 
size size of inverse FFT 
scale scaling specification 


Returns: int 
EDSP_OK success 


EDSP_BAD_ ARG size <4 
size not a power of 2 
size > max_fft_size 


Description: 


This routine calculates an inverse Fast Fourier Transform. The calculation is not-in-place, so the 
input and output arrays must not overlap. 


Notes: 


e The storage of complex data arrays is described in "Complex Array Format" in section 8.4.1, 
Overview. 


e Before calling this routine the lookup table and max_fft_size should be initialized by calling 
InitF ft. 


e Scaling specification is described in "Scaling" in section 8.4.1, Overview. 
e Only the bottom log, (size) bits of scale are used. 


e This routine is not re-entrant. 
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8.4.5 IfftReal 


Definition: 
int IfftReal (short op_x[ ], short scratch_y[ ], const short ip_x[ ], const short ip_y[ ], 
long size, long scale, int op_all_x) 
Arguments: 
op_x[ ] real output data 
scratch_y[ ] scratch memory or real output data 
ip_x{[ ] real part of positive input data 
ip_yl | imaginary part of positive input data 
size size of inverse FFT 
scale scaling specification 
op_all_x format specification of output data 


Returns: int 
EDSP_OK success 


EDSP_BAD_ARG size < 8 
size not a power of 2 
size > max_fft_size 
op_all_x #0 or 1 


Description: 
This routine calculates an inverse Fast Fourier Transform. 


ip_x and ip_y should contain the positive input data only. The negative data are simply the 
complex conjugate of the positive data. Since the input data values at both 0 and F,/2 can only be 
real, the F,/2 value should be placed in ip_y[0]. 


If op_all_x is 1, the output is stored in op_x. If op_all_x is 0, the first size/2 output data are stored 
in op_x; the remaining size/2 output data are stored in scratch_y. 


The calculation is not-in-place, so the input and output arrays must not overlap. 
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Notes: 


e Storage of complex and real data arrays is described in "Complex Array Format" and "Real 
Array Format" in section 8.4.1, Overview. 


e ip_x and ip_y should have size/2 elements. op_x should have size or size/2 elements as 
required by the value of op_all_x. 


e Before calling this routine the lookup table and max_fft_size should be initialized by calling 
InitF ft. 


e Scaling specification is described in "Scaling" in section 8.4.1, Overview. 
e Only the bottom log) (size) bits of scale are used. 


e This routine is not re-entrant. 
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8.4.6 FftInComplex 


Definition: 

int FftInComplex (short data_x[ ], short data_y[ ], long size, long scale) 
Arguments: 

data_x[ ] real part of data 

data_y[ ] imaginary part of data 

size size of FFT 

scale scaling specification 


Returns: int 
EDSP_OK success 


EDSP_BAD_ARG _ size<4 
size not a power of 2 
size > max_fft_size 


Description: 
This routine calculates an in-place complex Fast Fourier Transform. 
Notes: 


e The storage of complex data arrays is described in "Complex Array Format" in section 8.4.1, 
Overview. 


e Before calling this routine the lookup table and max_fft_size should be initialized by calling 
InitF ft. 


e Scaling specification is described in "Scaling" in section 8.4.1, Overview. 
e Only the bottom log) (size) bits of scale are used. 


e This routine is not re-entrant. 
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8.4.7 FftInReal 


Definition: 

int FftInReal (short data_x[ ], short data_y[ ], long size, long scale, int ip_all_x) 
Arguments: 

data_x[ ] real data on input, real part of positive data on output 

data_y[ ] real data or unused on input, imaginary part of positive data on output 

size size of FFT 

scale scaling specification 

ip_all_x format specification of input data 


Returns: int 
EDSP_OK success 


EDSP_BAD_ARG size < 8 
size not a power of 2 
size > max_fft_size 
ip_all_ x #0 or 1 


Description: 
This routine calculates an in-place real Fast Fourier Transform. 


The format of the input data is specified by ip_all_x. If ip_all_x is 1, the input data are taken from 
the data_x. If ip_all_x is 0, the first size/2 data are taken from data_x, and the remaining size/2 
data are taken from data_y. 


On returning, data_x and data_y contain size/2 positive data only. The negative output data are 
simply the complex conjugate of the positive data. Since the output data at both 0 and F,/2 are real, 
the F,/2 value is placed in data_y[0] 
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Notes: 


e Storage of complex and real data arrays is described in "Complex Array Format" and "Real 
Array Format" in section 8.4.1, Overview. 


e data_y should have size/2 elements. data_x should have size or size/2 elements as required by 
the value of op_all_x. 


e Before calling this routine the lookup table and max_fft_size should be initialized by calling 
InitF ft. 


e Scaling specification is described in "Scaling" in section 8.4.1, Overview. 
e Only the bottom log (size) bits of scale are used. 


e This routine is not re-entrant. 
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8.4.8 IfftInComplex 


Definition: 

int IfftInComplex (short data_x[ ], short data_y[ ], long size, long scale) 
Arguments: 

data_x[ ] real part of data 

data_y[ ] imaginary part of data 

size size of inverse FFT 

scale scaling specification 


Returns: int 
EDSP_OK success 


EDSP_BAD_ARG  size<4 
size not a power of 2 
size > max_fft_size 


Description: 
This routine calculates an in-place complex inverse Fast Fourier Transform. 


Notes: 


e The storage of complex data arrays is described in "Complex Array Format" in section 8.4.1, 
Overview. 


e Before calling this routine the lookup table and max_fft_size should be initialized by calling 
InitF ft. 


e Scaling Specification is described in "Scaling" in section 8.4.1, Overview. 
e Only the bottom log, (size) bits of scale are used. 


e This routine is not re-entrant. 
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8.4.9 IfftInReal 


Definition: 

int IfftInReal (short data_x[ ], short data_y[ ], long size, long scale, int op_all_x) 
Arguments: 

data_x[ | real part of positive data on input, real data on output 

data_y[ ] imaginary part of positive data on input, real data or unused on output 

size size of inverse FFT 

scale scaling specification 

op_all_x format specification of output data 


Returns: int 
EDSP_OK 


EDSP_BAD_ARG 


Description: 


Success 


size < 8 

size not a power of 2 
size > max_fft_size 
op_all_x #0 or l 


This routine calculates an in-place real inverse Fast Fourier Transform. 


data_x and data_y should contain positive input data only. The negative data are simply the 
complex conjugate of the positive data. Since the input data values at both 0 and F,/2 can only be 
real, the F,/2 value should be placed in data_y[0]. 


If op_all_x is 1, the output is stored in data_x. If op_all_x is 0, the first size/2 output data are 
stored in data_x; the remaining size/2 output data are stored in data_y. 
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Notes: 


e Storage of complex and real data arrays is described in "Complex Array Format" and "Real 
Array Format" in section 8.4.1, Overview. 


e data_y should all have size/2 elements. data_x should have size or size/2 elements as required 
by the value of op_all_x. 


e Before calling this routine the lookup table and max_fft_size should be initialized by calling 
InitF ft. 


e Scaling specification is described in "Scaling" in section 8.4.1, Overview 
e Only the bottom log, (size) bits of scale are used. 


e This routine is not re-entrant. 
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8.4.10 LogMagnitude 


Definition: 
int LogMagnitude (short output[ ], const short ip_x[ ], const short ip_y[ ], 
long no_elements, float fscale) 
Arguments: 
output[ ] real output data z 
ip_x[ ] real part of input data x 
ip_y[ ] imaginary part of input data y 
no_elements number of output data N 
fscale output scaling factor 


Returns: int 
EDSP_OK success 


EDSP_BAD_ARG no_elements < | 
no_elements > 32767 
|fscale| > 2'°/(10log1o2°") 


Description: 


This routine calculates the log magnitude of the complex input data in decibels, and writes the 
scaled result into the output array: 


z(n)=1 Ofscale-log,9(x(n)*-+y(n)’) O0<n<N 
Notes: 


e The storage of complex data arrays is described in "Complex Array Format" in section 8.4.1, 
Overview. 
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8.4.11 InitF ft 


Definition: 
int InitFft (long max_size) 
Arguments: 
max_size Maximum size of FFT that will be required. 


Returns: int 
EDSP_OK 
EDSP_NO_HEAP 


EDSP_BAD_ARG 


Description: 


success 
insufficient space available from malloc 


max_size < 2 
max_size not a power of 2 
max_size > 32768 


This routine generates the (quarter size) lookup table used by the FFT functions. The lookup tables 
are stored in memory allocated by malloc. 


Once the lookup tables have been generated the global variable max_fft_size is updated to indicate 
the maximum permitted FFT size. 


This routine must be called before calling first FFT. 


Notes: 


e The lookup tables are generated for the specified transform size. Smaller transforms will be 
performed using the same lookup tables. 


e The addresses of the lookup tables are stored in internal variables; they should not be accessed 


by user program. 


e This routine is not re-entrant. 
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8.4.12 FreeFft 
Definition: 

void FreeF ft (void) 
Arguments: none 
Returns: void 
Description: 


This routine release the memory used for FFT lookup tables and sets the global variable 
max_fft_size to zero. If FFT is calculated after calling this routine, InitFft must be called again 
before calling FFT. 


Notes: 


e This routine is not re-entrant. 
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8.5 Window Function 


8.5.1 Overview 
Contents: 


GenBlackman Generate a Blackman window. 


GenHamming Generate a Hamming window. 
GenHanning Generate a Hanning window. 
GenTriangle Generate a Triangle window. 
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8.5.2 GenBlackman 


Definition: 

int GenBlackman (short output[ ], long win_size) 
Arguments: 

output[ ] output data w(n) 

win_size window size N 


Returns: int 
EDSP_OK success 
EDSP_BAD_ARG win_size < 1 
Description: 


This routine generates a Blackman window in output. VectorMult can be used to apply the 
window to a data array. 


The function used is: 


Won = 235 - [oe - DSc0s( 5 + 0.08ecs( 2" | Osnen 
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8.5.3 GenHamming 


Definition: 

int GenHamming (short output[ ], long win_size) 
Arguments: 

output[ ] output data w(n) 

win_size window size N 


Returns: int 
EDSP_OK success 
EDSP_BAD_ARG win_size < | 
Description: 


This routine generates a Hamming window in output. VectorMult can be used to apply the 
window to a data array. 


The function used is: 


Wen) = (215 -1yfosa -Odcos( 2") ] OsneN 
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8.5.4 GenHanning 


Definition: 

int GenHanning (short output[ ], long win_size) 
Arguments: 

output | output data w(n) 

win_size window size N 


Returns: int 
EDSP_OK success 
EDSP_BAD_ARG  win_size< 1 
Description: 


This routine generates a Hanning window in output. VectorMult can be used to apply the window 
to a data array. 


The function used is: 


we = Aft - cos] OsnenN 
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8.5.5 GenTriangle 


Definition: 

int GenTriangle (short output[ ], long win_size) 
Arguments: 

output[ ] output data w(n) 

win_size window size N 


Returns: int 
EDSP_OK success 
EDSP_BAD_ARG win_size < | 
Description: 


This routine generates a Triangular window in output. VectorMult can be used to apply the 
window to a data array. 


The function used is: 


n+ 1) ] OsneN 


wig = 25 -yf1- 
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8.6 Filters 


8.6.1 Overview 
Contents: 
Fir Implement a finite impulse response filter. 
Firl Implement a finite impulse response filter for a single input data. 
lir Implement an infinite impulse response filter. 
lirl Implement an infinite impulse response filter for a single input data. 
Dlir Implement a double precision infinite impulse response filter. 
Dliirl Implement a double precision infinite impulse response filter for a single input 
data. 
Lms Implement a real adaptive FIR filter. 
Lms1 Implement a real adaptive FIR filter for a single input data. 
InitFir Initialize FIR filter. 
Initlir Initialize IIR filter. 
InitDlir _ Initialize double precision HR filter. 
InitLms Initialize LMS filter. 
FreeFir Release a workspace allocated by InitFir. 
Freelir Release a workspace allocated by Initlir. 
FreeDlir Release a workspace allocated by InitDlir. 
FreeLms_ Release a workspace allocated by InitLms. 


Note: When the filter functions are used in a program, filt_ws.h must be included. 


Coefficient Scaling: 


Filtering is likely to introduce saturation or quantization noise. It can be minimized by scaling the 
filter coefficients. However, the scaling of coefficients must be performed carefully to balance the 
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effects of saturation and quantization. If the coefficients are too large, saturation may occur; if 
they are too small, excessive quantization noise may be introduced. 


For FIR (finite impulse response) filters, no saturation will occur if 
coeffs[i] # H'8000 for all i 
Decefi < 2% 
res_shift = 24 
Here, coeff is a filter coefficient, and res_shift is the number of bits shifted to the right at output. 


For many input signals, smaller res_shift values (or larger coeff values) can be used with a low 
likelihood of saturation, but with significantly reduced quantization noise. If H'8000 may be 
among the inputs, all coeff values should be limited to the range from H'8001 to H'7FFF. 


IIR (infinite impulse response) filters have a recursive structure, which means that the scaling 
approach described above is inappropriate. 


LMS (least mean squared) adaptive filters obey the same conventions as FIR filters. However, the 
coefficients may be pushed into saturation as the coefficients are changed. In that case, the 
coefficients should not include H’8000. 


Workspace: 


Digital filters have state that must be preserved from the processing of one data to the next. This 
filter state, or workspace, must be stored in memory that can be accessed with minimum overhead 
- on the SH-DSP, the Y-RAM area is used. The workspace must be initialized by the Init function 
before calling filter function. 


The structure of the workspace memory is liable to change in the future, so user programs should 
not attempt to read or modify this memory, it should only be accessed by the library functions. 


Memory Usage: 


To allow efficient use of the SH-DSP for all filters, the coefficients must be located in X memory 
and the workspace must be located in Y memory. The input and output data may be located in any 
memory segment. 


The filter coefficient must be located in X memory using the #pragma section directive. 


Each individual filter is allocated workspace from a global buffer using the Init routines. The 
global buffer must be located in Y memory. 
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8.6.2 Fir 


Definition: 
int Fir (short output[ ], const short input[ ], long no_samples, const short coeff ], 
long no_coeffs, int res_shift, short *workspace) 
Arguments: 
output[ | output data y 
input | input data x 
no_samples number of data N 
coeff ] array of filter coefficients h 
no_coeffs number of coefficients K (length of filter) 
res_shift right shift applied to each output 
*workspace pointer to filter memory 


Returns: int 
EDSP_OK success 


EDSP_BAD_ ARG no_samples < 1 
no_coeffs < 2 
res_shift < 0 
res_shift > 25 


Description: 


This routine implements a finite impulse response (FIR) filter. It uses workspace to record the 
most recent input data. The result of filtering the data in input is written to output: 


ATL) = [ & mao x0 1) | gees shih 


For multiply-accumulate operation, the sum is accumulated in 39 bits. Each 16 bit output is 
extracted from the bottom 16 bits of res_shift bits shifted to the right. If an overflow occurs, output 
is saturated to positive or negative maximum value. 
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Notes: 


e Coefficient scaling is described in "Coefficient Scaling" in section 8.6.1, Overview. 
e Before calling this routine for a new filter, initialize the filter workspace by calling InitFir. 
e output may be the same as input in which case input is overwritten. 


e This routine is not re-entrant. 
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8.6.3 Firl 


Definition: 
int Firl (short *output, short input, const short coeff] ], long no_coeffs, int res_shift, 
short *workspace) 
Arguments: 
*output pointer to output data y(n) 
input input data x(n) 
coeff ] filter coefficients h 
no_coeffs number of coefficients K (length of filter) 
res_shift right shift applied to each output 
*workspace pointer to filter memory 


Returns: int 
EDSP_OK 


EDSP_BAD_ARG 


SuCCeSS 


no_coeffs < 2 


res_shift < 0 
res_shift > 25 


Description: 


This routine implements a finite impulse response (FIR) filter for a single input data only. It uses 
workspace to record the most recent input data. The result of filtering the data in input is written to 
output: 


AR) = [ & x90] . gptes_dhitt 


For multiply-accumulate operation, the sum is accumulated in 39 bits. Each 16 bit output is 
extracted from the bottom 16 bits of res_shift bits shifted to the right. If an overflow occurs, output 
is saturated to positive or negative maximum value. 
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Notes: 


e Coefficient scaling is described in "Coefficient Scaling" in section 8.6.1, Overview. 


e Before calling this routine for a new filter, initialize the filter workspace by calling InitFir. 
e This routine is not re-entrant. 
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8.6.4 lir 


Definition: 
int lir (short output[ ], const short input[ ], long no_samples, const short coeff] ], 
long no_sections, short *workspace) 
Arguments: 
output ] output data 
input[ ] input data 
no_samples number of data N 
coeff ] filter coefficients 


no_sections 

*workspace 
Returns: int 

EDSP_OK 


EDSP_BAD_ARG 


Description: 


number of second order filter sections K 


pointer to filter memory 


success 


no_samples < 1 
no_sections < | 
ao < 0 

ag, > 16 


This routine implements an infinite impulse response (IIR) filter. 


The filter is implemented as a cascade of K second order filters called biquads, with an additional 
scaling performed on the biquad output. The coefficients are specified in signed 16-bit fixed-point 


number and the output of each biquad is given by: 


dy (n)=[a1.d)(n-1)+ay,d,(n-2)+2"°x(n)}-2"° 


yx(n)=[bo.d)(n)+bj,d,(n-1)+bd,(n-2)] 2% 


The input to the section is the output of the previous section. The input to the first (k=0) section is 
taken from input. The output from the last (k = K-1) section is written to output. 
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The filter coefficients should be specified in coeff in the order: 


00, 210, 220, boo, bio, b20, Aoi, A115 21, boy... box-1 
Here, a, is the number of bits shifted to the right at biquad output. 
Each biquad is calculated in 32 bits using saturating arithmetic. Each biquad output is extracted 


from the bottom 16 bits of accumulator after 15 or ao, bits shifted to the right. If an overflow 
occurs, output is saturated to positive or negative maximum value. 


Notes: 


e Before calling this routine for a new filter, initialize the filter workspace by calling Initlir. 
¢ output may be the same as input in which case input is overwritten. 
e This routine is not re-entrant. 
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8.6.5 lirl 


Definition: 
int lirl (short *output, short input, const short coeff] ], long no_sections, 
short *workspace) 
Arguments: 
*output pointer to output data 
input input data 
coeff] | filter coefficients 
no_sections number of second order filter sections K 
*workspace pointer to filter memory 


Returns: int 
EDSP_OK success 


EDSP_BAD_ARG no_sections < | 
ao, < 0 
ag, > 16 


Description: 
This routine implements an infinite impulse response (IIR) filter for a single input data only. 


The filter is implemented as a cascade of K second order filters called biquads, with an additional 
scaling performed on the biquad output. The coefficients are specified in signed 16-bit fixed-point 
number and the output of each biquad is given by: 


dy (n)=[ay,d,(n-1)+ay4d,(n-2)+2'°x(n)]-2° 
ye(1)=[boxdy(n) +b, dj (n-1)+b.d,(n-2)] 2% 


The input to the section is the output of the previous section. The input to the first (k=0) section is 
taken from input. The output from the last (k = K-1) section is written to output. 


The filter coefficients should be specified in coeff in the order: 


00, 210, 420, Doo, bio, 20, Aoi, 211, 821, Boy... box-1 


Here, ao, is the number of bits shifted to the right at biquad output. 
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Each biquad is calculated in 32 bits using saturating arithmetic. Each biquad output is extracted 
from the bottom 16 bits of accumulator after 15 or ao, bits shifted to the right. If an overflow 
occurs, output is saturated to positive or negative maximum value. 


Notes: 


e Before calling this routine for a new filter, initialize the filter workspace by calling Initlir. 
e This routine is not re-entrant. 
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8.6.6 Diir 


Definition: 
int Dhr (short output[ ], const short input[ ], long no_samples, const long coeff ], 
long no_sections, long *workspace) 
Arguments: 
output[ | output data 
input[ ] input data 
no_samples number of data N 
coeff] | filter coefficients 
no_sections number of second order filter sections K 
*workspace pointer to filter memory 


Returns: int 
EDSP_OK success 


EDSP_BAD ARG no_samples < 1 
no_sections < 1 
ag, <3 
ao, > 32 fork < K-1 
ag, > 48 fork = K-1 


Description: 


This routine implements an infinite impulse response (IIR) filter with double precision 
coefficients. 


The filter is implemented as a cascade of K second order filters called biquads, with an additional 
scaling performed on the biquad output. The coefficients are specified in signed 32-bit fixed-point 
number and the output of each biquad is given by: 


dy (n)=[a1.d,(n-1)+ay.dy(n-2)+2”x(n)]-27) 
yx(n)=[boxd(n)+b 1,d,(n-1)+b>,d,(n-2)] 2% 2? 


The input to the section is the output of the previous section. The input to the first (k=0) section is 
taken from input after 16 bits shifted to the left. The output from the last (k = K-1) section is 
written to output. 
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The filter coefficients should be specified in coeff in the order: 


00, 210, 420, boo, bio, bz0, Aor, 211, 221, Dor... bax-1 


Here, ao, is the number of bits shifted to the right at biquad output. 


Dlir differs from lir in that the filter coefficients are specified as 32 rather than 16 bit values. For 
multiply-accumulate operation, the sum is accumulated in 64 bits. Intermediate biquad outputs are 
extracted from the bottom 32 bits of accumulator after ao, bits shifted to the right. If an overflow 
occurs, Output is saturated to positive or negative maximum value. 


In the final stage, output is extracted from the bottom 16 bits of accumulator after agx., bits shifted 
to the right. If an overflow occurs, output is saturated to positive or negative maximum value. 


Notes: 


e Before calling this routine for a new filter, initialize the filter by calling InitDlir. 
e Delay nodes are rounded and saturated to 30 bit quantities. 


e The most common use of Dlir specifies the coefficients in signed 32-bit fixed-point number. In 
this case, ag, should be set to 31 for k < K-1 and to 47 for k = K-1. 


e When possible, lir should be used in preference to Dlir as it runs aster on the SH-DSP. 
¢ output may be the same as input in which case input is overwritten. 
e This routine is not re-entrant. 
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8.6.7 Diirl 


Definition: 
int Dlirl (short *output, short input, const long coeff] ], long no_sections, 
long *workspace) 
Arguments: 
*output pointer to output data 
input input data 
coeff ] filter coefficients 
no_sections number of second order filter sections K 
*workspace pointer to filter memory 


Returns: int 
EDSP_OK success 


EDSP_BAD_ARG no_sections < 1 
ao <3 
ao, > 32 for k < K-1 
ao. > 48 for k = K-1 


Description: 


This routine implements a double precision infinite impulse response (IIR) filter for a single input 
data only. 


The filter is implemented as a cascade of K second order filters called biquads, with an additional 
scaling performed on the biquad output. The coefficients are specified in signed 32-bit fixed-point 
number and the output of each biquad is given by: 


dy (n)=[a1xdy(n-1)+aoxdy(n-2)+2”x(n)]-27" 
y(t) =[boxdk()-+b 1xdy(n-1)+b4d,(n-2)] 2% 2? 


The input to the section is the output of the previous section. The input to the first (k=0) section is 
taken from input after 16 bits shifted to the left. The output from the last (k = K-1) section is 
written to output. 
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The filter coefficients should be specified in coeff in the order: 


A905 10, 220, boo, bio, ba, Aoi, Ai, A21, Dor... Dox-1 


Here, ao, is the number of bits shifted to the right at biquad output. 


Dlir differs from lir in that the filter coefficients are specified as 32 rather than 16 bit values. For 
multiply-accumulate operation, the sum is accumulated in 64 bits. Intermediate biquad outputs are 
extracted from the bottom 32 bits of accumulator after ao, bits shifted to the right. If an overflow 
occurs, output is saturated to positive or negative maximum value. 


In the final stage, output is extracted from the bottom 16 bits of accumulator after aox.; bits shifted 
to the right. If an overflow occurs, output is saturated to positive or negative maximum value. 


Notes: 


e Before calling this routine for a new filter, initialize the filter by calling InitDlir. 
e Delay nodes are rounded and saturated to 30 bit quantities. 


e The most common use of Dlir specifies the coefficients in signed 32-bit fixed-point number. In 
this case, ao, should be set to 31 for k < K-1 and to 47 for k = K-1. 


e When possible lir should be used in preference to Dlir as it runs faster on the SH-DSP. 
e This routine is not re-entrant. 


Rev. 1.0, 09/98, page 373 of 476 


HITACHI 


8.6.8 Lms 


Definition: 
int Lms (short output[ ], const short input[ ], const short ref_output[ ], 
long no_samples, short coeff] ], long no_coeffs, int res_shift, short conv_fact, 
short *workspace) 
Arguments: 
output[ ] output data y 
input[ ] input data x 
ref_output[ ] desired output value d 
no_samples number of data N 
coeff_x[ ] adaptive filter coefficients h 
no_coeffs number of coefficients K 
res_shift right shift applied to each output 
conv_fact convergence factor 2u 
*workspace_y pointer to filter memory 


Returns: int 
EDSP_OK success 


EDSP_BAD_ARG no_samples < | 
no_coeffs < 2 
res_shift < 0 
res_shift > 25 
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Description: 
This routine implements a real adaptive FIR filter using the least mean square algorithm. 


The FIR filter is defined as: 


yin) = [= x09 200-19] _ ee ait 


For multiply-accumulate operation, the sum is accumulated in 39 bits. Each 16 bit output is 
extracted from the bottom 16 bits of res_shift bits shifted to the right. If an overflow occurs, output 
is saturated to positive or negative maximum value. 


The Widrow-Hoff algorithm is used to update the filter coefficients: 


hy+i(k)=h,(k)+2pe(n)x(n-k) 


where e(n) is the (saturated) error between the desired signal and the actual filter output: 


e(n)=d(n)-y(n) 


The calculation of requires two (16 bit) x (16 bit) multiplies. In both multiplies, upper 16 bits is 
stored and if an overflow occurs, data are saturated to positive or negative maximum value. If 
updated coefficients include H’8000, an overflow may occur for multiply-accumulate operation. 
In this case, the coefficients must set in the range from H’8001 to H’7FFF. 


Notes: 


e Coefficient specification is described in "Coefficient Scaling" in section 8.6.1, Overview. 


As the coefficients are adapted by LMS filters, the safest scaling scheme is to use fewer than 
256 coefficients and set res_shift to 24. 


e conv_fact should normally be positive; it should never be H’8000. 
e Before calling this routine for a new filter, initialize the filter workspace by calling InitLms. 
¢ output may be the same as input or ref_output in which case input or ref_output is overwritten. 


e This routine is not re-entrant. 
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8.6.9 Lms1 


Definition: 

int Lms1 (short *output, short input, short ref_output, short coeff[ ], long no_coeffs, 

int res_shift, short conv_fact, short *workspace) 

Arguments: 

*output pointer to output data y(n) 

input input data x(n) 

ref_output desired output value d(n) 

coeff] | adaptive filter coefficients h 

no_coeffs number of coefficients K 

res_shift right shift applied to each output 

conv_fact convergence factor 2u 

*workspace pointer to filter memory 


Returns: int 
EDSP_OK success 
EDSP_BAD_ ARG no_coeffs < 2 
res_shift < 0 
res_shift > 25 


Returns: int 


This routine implements a real adaptive FIR filter using the least mean square algorithm, for a 
single input data. 


The FIR filter is defined as: 


"I = [ & x0020-19] . genes shat 
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For multiply-accumulate operation, the sum is accumulated in 39 bits. Each 16 bit output is 
extracted from the bottom 16 bits of res_shift bits shifted to the right. If an overflow occurs, output 
is saturated to positive or negative maximum value. 


The Widrow-Hoff algorithm is used to update the filter coefficients: 


hy+i(k)=h,(k)+2pe(n)x(n-k) 


where e(n) is the (saturated) error between the desired signal and the actual filter output: 


e(n)=d(n)-y(n) 


The calculation of requires two (16 bit) x (16 bit) multiplies. In both multiplies, upper 16 bits is 
stored and if an overflow occurs, data are saturated to positive or negative maximum value. If 
updated coefficients include H’8000, an overflow may occur for multiply-accumulate operation. 
In this case, the coefficients must set in the range from H’8001 to H’7FFF. 


Notes: 


e Coefficient specification is described in "Coefficient Scaling" in section 8.6.1, Overview. 


As the coefficients are adapted by LMS filters, the safest scaling scheme is to use fewer than 
256 coefficients and set res_shift to 24. 


e conv_fact should normally be positive; it should never be H’8000. 

e Before calling this routine for a new filter, initialize the filter workspace by calling InitLms. 

¢ output may be the same as input or ref_output in which case input or ref_output is overwritten. 
e This routine is not re-entrant. 
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8.6.10  InitFir 


Definition: 
int InitFir (short **workspace, long no_coeffs) 

Arguments: 
**workspace pointer to pointer to buffer reserved for filter memory 
no_coeffs number of coefficients K 


Returns: int 
EDSP_OK success 
EDSP_NO_HEAP insufficient space available from workspace buffer 
EDSP_BAD_ARG  no_coeffs < 2 

Description: 


This routine allocates the memory required for subsequent calls to Fir and Firl. Previous input 
data are initialized to zero. 


Notes: 


e The workspace buffer allocated by InitFir should only be manipulated by Fir, Firl, Lms and 
Lms1. It should not be accessed by user program. 


e filt_ws.h must be included. 


e This routine is not re-entrant. 
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8.6.11  Initlir 


Definition: 
int Initlir (short **workspace, long no_sections) 
Arguments: 
** workspace pointer to pointer to buffer reserved for filter memory 


no_sections 
Returns: int 
EDSP_OK 
EDSP_NO_HEAP 
EDSP_BAD_ARG 


Description: 


number of second order filter sections K 


success 
insufficient space available from workspace buffer 


no_sections < | 


This routine allocates the memory required for subsequent calls to lir and Iirl. All delay node 
values are initialized to zero. 


Notes: 


e The workspace buffer allocated by Initlir should only be manipulated by Iir and Iir1. It should 
not be accessed by user program. 


e filt_ws.h must be included. 


e This routine is not re-entrant. 
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8.6.12 InitDIir 


Definition: 
int InitDlir (long **workspace, long no_sections) 
Arguments: 
**workspace pointer to pointer to buffer reserved for filter memory 


no_sections 
Returns: int 
EDSP_OK 
EDSP_NO_HEAP 
EDSP_BAD_ARG 


Description: 


number of second order filter sections K 


success 
insufficient space available from workspace buffer 


no_sections < | 


This routine allocates the memory required for subsequent calls to Dir and Dlirl. All delay node 
values are initialized to zero. 


Notes: 


e The workspace buffer allocated by InitDlir should only be manipulated by Dlir and Dlir1. It 
should not be accessed by user program. 


e  filt_ws.h must be included. 


e This routine is not re-entrant. 
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8.6.13 InitLms 


Definition: 
int InitLms (short **workspace, long no_coeffs) 

Arguments: 
**workspace pointer to pointer to buffer reserved for filter memory 
no_coeffs number of coefficients K 


Returns: int 
EDSP_OK success 
EDSP_NO_HEAP insufficient space available from workspace buffer 
EDSP_BAD_ARG __ no_coeffs < 2 

Description: 


This routine allocates the memory required for subsequent calls to Lms and Lms1. Previous input 
samples is initialized to zero. 


Notes: 


e The workspace buffer allocated by InitLms should only be manipulated by Fir, Firl, Lms and 
Lms|1. It should not be accessed by user program. 


e  filt_ws.h must be included. 


e This routine is not re-entrant. 


Rev. 1.0, 09/98, page 381 of 476 
HITACHI 


8.6.14 FreeFir 


Definition: 
int FreeFir (short **workspace, long no_coeffs) 

Arguments: 
**workspace pointer to pointer to buffer reserved for filter memory 
no_coeffs number of coefficients K 


Returns: int 
EDSP_OK success 
EDSP_BAD_ARG no_coeffs < 2 
Description: 
This routine frees workspace memory previously allocated by InitFir. 
Notes: 


e This routine is not re-entrant. 
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8.6.15‘ Freelir 


Definition: 
int Freelir (short **workspace, long no_sections) 

Arguments: 
** workspace pointer to pointer to buffer reserved for filter memory 
no_sections number of second order filter sections K 


Returns: int 
EDSP_OK success 
EDSP_BAD_ARG _no_sections < 1 
Description: 
This routine frees workspace memory previously allocated by Initlir. 
Notes: 


e This routine is not re-entrant. 
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8.6.16 FreeDlir 


Definition: 
int FreeDlhr (long **workspace, long no_sections) 

Arguments: 
** workspace pointer to pointer to buffer reserved for filter memory 
no_sections number of second order filter sections K 


Returns: int 
EDSP_OK success 
EDSP_BAD_ARG no_sections < 2 
Description: 
This routine frees workspace memory previously allocated by InitDlir. 
Notes: 


e This routine is not re-entrant. 
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8.6.17 FreeLms 


Definition: 
int FreeLms (short **workspace, long no_coeffs) 

Arguments: 
**workspace pointer to pointer to buffer reserved for filter memory 
no_coeffs number of coefficients K 


Returns: int 
EDSP_OK success 
EDSP_BAD_ARG no_sections < 1 
Description: 
This routine frees workspace memory previously allocated by InitLms. 
Notes: 


e This routine is not re-entrant. 
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8.7 Convolution and Correlation 


8.7.1 Overview 

Contents: 
ConvComplete 
ConvCyclic 
ConvPartial 
Correlate 


CorrCyclic 


Calculate the complete convolution of two arrays. 
Calculate the cyclic convolution of two arrays. 
Calculate the partial convolution of two arrays. 
Calculate the correlation between two arrays. 


Calculate the cyclic correlation between two arrays. 


In each case, one of two input arrays must be located in X memory and the other in Y memory. 
The output array may be located in any memory area. 
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8.7.2 ConvComplete 


Definition: 
int ConvComplete (short output[ ], const short ip_x[ ], const short ip_y[ ], long x_size, 
long y_size, int res_shift) 
Arguments: 
output[ ] output z 
ip_x[ ] input x 
ip_y[ ] input y 
X_size size of ip_x X 
y_size size of ip_y Y 
res_shift right shift applied to each output 


Returns: int 
EDSP_OK success 
EDSP_BAD_ARG x_size < | 
y_size < | 
res_shift < 0 
res_shift > 25 


Description: 


This routine completely convolves the two input arrays and puts the result in the output array: 


-1 
Fil) = b xi) wan 9 | - tes chat OsmeX+¥-1 
1=0 
Elements outsides the input array are read as zero. 
Notes: 


e The output array size must be set more than X + Y - 1. 
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8.7.3 ConvCyclic 


Definition: 
int ConvCyclic (short output[ ], const short ip_x[ ], const short ip_y[ ], long size, 
int res_shift) 
Arguments: 
output[ ] output z 
ip_x[ ] input x 
ip_yl ] input y 
size size of arrays N 
res_shift right shift applied to each output 


Returns: int 
EDSP_OK success 
EDSP_BAD_ARG size < 1 
res_shift < 0 
res_shift > 25 


Description: 


This routine cyclically convolves the two input arrays and puts the result in the output array: 


« 
are) = b n(i) Je - i+ who | - geees_abatt OgmeN 
i=0 


where |i\y is residue of i modulo N. 
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8.7.4 ConvPartial 


Definition: 
int ConvPartial (short output[ ], const short ip_x[ ], const short ip_y[ ], long x_size, 
long y_size, int res_shift) 
Arguments: 
output[ ] output z 
ip_x[ ] input x 
ip_yl ] input y 
X_size size of ip_x, X 
y_size size of ip_y, Y 
res_shift right shift applied to each output 


Returns: int 
EDSP_OK 


EDSP_BAD_ARG 


Description: 


This routine convolves the two input arrays but does not include outputs derived from elements 


success 


X_size < | 
y_size < 1 
res_shift < 0 
res_shift > 25 


outside the array boundaries: 


om | 
aril) = b ati) béra+ A- 1 -i|  gtes_chatt 
i=0O 


where a is the smaller input array, A is its size, b is the other array and B is its size. 


Notes: 


e The output array size must be set more than |X-Y|+1. 


e Elements outside the input arrays are read as zero. 


HITACHI 


Osms [a -B] 
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8.7.5 Correlate 


Definition: 

int Correlate (short output[ ], const short ip_x[ ], const short ip_y[ ], long x_size, 

long y_size, long no_corr, int x_is_larger, int res_shift) 

Arguments: 

output[ ] output z 

ip_x[ ] input x 

ip_y[ ] input y 

x_size size of ip_x X 

y_size size of ip_y Y 

no_corr number of correlations M 

x_is_larger array specification, if X=Y 

res_shift right shift applied to each output 


Returns: int 
EDSP_OK success 


EDSP_BAD_ARG x_size < | 
y_size < | 
no_corr < | 
res_shift <0 
res_shift > 25 
x_is_larger # 0 or 1 


Description: 


This routine correlates the two input arrays and puts the result in the output array. In this 
calculation a is the larger input array, A is its size, b is the other input (if X and Y are equal 
x_is_larger defines a to be x). Then: 


-l 
arij= [Eso va+x0] - Qaeda OsmeM 
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A < X+M is permissible. In this case, elements outsides the input arrays are read as zero. 
Notes: 


e res_shift = 0 corresponds to an integer calculation. 


res_shift = 15 corresponds to a fractional calculation. 
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8.7.6 CorrCyclic 


Definition: 
int CorrCyclic (short output[ ], const short ip_x[ ], const short ip_y[ ], long size, 
int reverse, int res_shift) 
Arguments: 
output[ ] output z 
ip_x[ ] input x 
ip_yl ] input y 
size size of arrays N 
reverse reverse flag 
res_shift right shift applied to each output 


Returns: int 
EDSP_OK success 
EDSP_BAD_ARG size < | 
res_shift < 0 


res_shift > 25 
reverse # 0 or | 


Description: 


This routine cyclically correlates x with y and puts the result in the output array z: 


«1 
ari) = [= xi) wit rah) | -gte_shat OsmeH 


where |i\y is residue of i modulo N. If reverse is 1 the elements in output are reversed, to give the 
effective calculation: 


{-1 
ari) = a i) ai + ral) | Qe shit OsmeN 
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8.8 Miscellaneous 

8.8.1 Overview 

Contents: 
Limit Exchange data from H’8000 to H’8001. 
CopyXtoY Copy array from X memory to Y memory. 
CopyYtoX Copy array from Y memory to X memory. 
CopyToxX Copy array from anywhere to X memory. 
CopyToY Copy array from anywhere to Y memory. 
CopyFromX Copy array from X memory to anywhere. 
CopyFromY Copy array from Y memory to anywhere. 
GenGWnoise Generate Gaussian white noise. 
MatrixMult Multiply two matrices. 
VectorMult Multiply two data. 
MsPower Calculate mean square power. 
Mean Calculate mean. 
Variance Calculate mean and variance. 
MaxlI Find maximum of integer array. 
Minl Find minimum of integer array. 
PeakI Find maximum absolute value of integer array. 
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8.8.2 Limit 


Definition: 

int Limit (short data_xy[ ], long no_elements, int data_is_x) 
Arguments: 

data_xy data array 

no_elements number of elements 

data_is_x location specification of data 


Returns: int 
EDSP_OK success 


EDSP_BAD_ARG no_elements < 1 
data_is x #0or 1 


Description: 


This routine exchanges data from H’8000 to H’8001. Therefore an overflow does not occur for 
fixed-point multiply operation. Even if this routine is performed, an overflow may occur for 
accumulate operation. 


Notes: 


e If data_is_x is 1, data_xy should be located in X memory. 
If data_is_x is 0, data_xy should be located in Y memory. 
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8.8.3 CopyXtoY 


Definition: 

int CopyXtoY (short op_y[ ], const short ip_x[ ], long 
Arguments: 

op_y[ ] output data 

ip_x[ ] input data 

n number of elements 


Returns: int 
EDSP_OK success 
EDSP_BAD_ARG__ n< 1 
Description: 
This routine copies the array ip_x to op_y. 


Notes: 


n) 


e ip_x is located in X memory and op_y is located in Y memory. 


HITACHI 
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8.8.4 CopyYtox 


Definition: 

int CopyYtoX (short op_x[ ], const short ip_y[ ], long n) 
Arguments: 

op_x[ ] output data 

ip_y[ ] input data 

n number of elements 


Returns: int 
EDSP_OK success 
EDSP_BAD_ARG n<l 
Description: 
This routine copies the array ip_y to op_x. 
Notes: 


e op_x is located in X memory and ip_y is located in Y memory. 


Rev. 1.0, 09/98, page 396 of 476 
HITACHI 


8.8.5 CopyTox 


Definition: 

int CopyToX (short op_x[ ], const short input[ ], long n) 
Arguments: 

op_x[ ] output data 

input[ ] input data 

n number of elements 


Returns: int 
EDSP_OK success 
EDSP_BAD_ARG__ n< 1 
Description: 
This routine copies the array input to op_x. 
Notes: 


© op_x is located in X memory and input is located in any memory area. 
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8.8.6 CopyToY 


Definition: 

int CopyToY (short op_y[ ], const short input[ ], long n) 
Arguments: 

op_yl ] output data 

input[ ] input data 

n number of elements 


Returns: int 
EDSP_OK success 
EDSP_BAD_ARG n<1l 
Description: 
This routine copies the array input to op_y. 
Notes: 


e op_y is located in Y memory and input is located in any memory area. 
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8.8.7 CopyFromX 


Definition: 

int CopyFromX (short output[ ], const short ip_x[ ], long n) 
Arguments: 

output[ | output data 

ip_x[ ] input data 

n number of elements 


Returns: int 
EDSP_OK success 
EDSP_BAD_ARG__ n< 1 
Description: 
This routine copies the array ip_x to output. 
Notes: 


e ip_x is located in X memory and output is located in any memory area. 
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8.8.8 CopyFromY 


Definition: 

int CopyFromY (short output[ ], const short ip_y[ ], long n) 
Arguments: 

output[ | output data 

ip_yl ] input data 

n number of elements 


Returns: int 
EDSP_OK success 
EDSP_BAD_ARG n<1l 
Description: 
This routine copies the array ip_y to output. 
Notes: 


e ip_y is located in Y memory and output is located in any memory area. 
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8.8.9 GenGWhnoise 


Definition: 

int GenGWhoise (short output[ ], long no_samples, float variance) 
Arguments: 

output[ | output white noise data 

no_samples number of data 

variance variance of noise distribution o7 


Returns: int 
EDSP_OK suCCeSS 
EDSP_BAD_ARG no_samples < 1 
variance < 0.0 
Description: 


This routine generates Gaussian white noise with zero mean and user-specified variance. Output 
data are produced in pairs. To produce a pair of output data, the standard random number 
generator provided by rand is used to generate pairs of random numbers ¥, and y2 between -1 and 
1, until a pair is found whose sum of squares x is less than 1. The pair of output data 0;,0> are then 
calculated: 


Oy = ypf-2 Ina 
02. = Syary-2 Inge 


Notes: 


e [fan odd number of data is requested, the second data of the last pair is discarded. 


e This routine is not strictly re-entrant since any calls to rand in an interrupt routine or between 
calls to this routine will affect the sequence of random numbers used. However, such calls will 
not affect the random properties of the white noise generated. 

e Floating point arithmetic is used in this function, so its use should be restricted to test 
programs rather than application programs whenever possible. 
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8.8.10 MatrixMult 


Definition: 
int MatrixMult (void *op_matrix, const void *ip_x, const void *ip_y, long m, long n, 
long p, int x_first, int res_shift) 
Arguments: 
*op_matrix pointer to first element of output 
*ip_x pointer to first element of input x 
*ip_y pointer to first element of input y 
m row dimension of matrix 
n column dimension of matrix1, row dimension of matrix2 
p column dimension of matrix2 
x_first order specification of matrix multiply 
res_shift right shift applied to each output 


Returns: int 
EDSP_OK success 


EDSP_BAD_ARG m,norp< 1 
res_shift < 0 
res_shift > 25 
x_first # 0 or 1 


Description: 
This routine multiplies the two matrices ip_x and ip_y and stores the result in op_matrix. 


If x_first is 1 the product x.y is calculated. In this case ip_x is m X n, ip_y is n X p and op_matrix 
ism * p. 


If x_first is 0 the product y.x is calculated. In this case ip_y is m X n, ip_x is n X p and op_matrix 
ism * p. 
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For multiply-accumulate operation, the sum is accumulated in 39 bits. Each 16 bit output is 
extracted from the bottom 16 bits of res_shift bits shifted to the right. If an overflow occurs, output 
is saturated to positive or negative maximum value. 


Each matrix is stored in the normal ‘C’ manner (row major order): 
a 3] 3 
4 aS 3 OF 
33 39 S10 All 

Notes: 


e The function prototype specifies the array parameters as void * to allow arbitrary array sizes to 
be specified. These parameters should point to short data. 


e ip_x, ip_y and op_matrix must not overlap. 
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8.8.11 VectorMult 


Definition: 
int VectorMult (short output[ ], const short ip_x[ ], const short ip_y[ ], 
long no_elements, int res_shift) 
Arguments: 
output[ ] output 
ip_x[ ] input! 
ip_y[ ] input2 
no_elements number of elements 
res_shift right shift applied to each output 


Returns: int 
EDSP_OK success 


EDSP_BAD_ARG no_elements < 1 
res_shift < 0 
res_shift > 16 


Description: 
This routine multiplies pairs of elements from ip_x and ip_y and stores the results in output. 
Notes: 


e Output is extracted from the bottom 16 bits of res_shift bits shifted to the right. If an overflow 
occurs, output is saturated to positive or negative maximum value. 

e This routine performs element-wise multiplications. To calculate a dot product use MatrixMult 
with m and p set to 1. 
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8.8.12 MsPower 


Definition: 

int MsPower (long *output, const short input[ ], long no_elements, int src_is_x) 
Arguments: 

*output pointer to result 

input[ | input x 

no_elements number of elements N 

src_is_X location specification of data 


Returns: int 
EDSP_OK success 


EDSP_BAD_ARG no_elements < | 
src_is x #0or 1 


Description: 


This routine calculates the Mean Square Power of the input data: 


H-1 
es 2 
Teen squade power = Tr MH 


Notes: 


e The division result is rounded to the nearest integral value. 
e The sum is accumulated in 63 bits. If no_elements is more than 2°”, overflow may occur. 
e Ifsrc_is _x is 1, data is located in X memory. 


If src_is_x is 0, data is located in Y memory. 
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8.8.13 Mean 


Definition: 

int Mean (short *mean, const short input[ ], long no_elements, int src_is_x) 
Arguments: 

*mean pointer to mean of data in input 

input[ | input x 

no_elements number of elements N 

ste_is_ x location specification of data 


Returns: int 
EDSP_OK success 


EDSP_BAD_ARG no_elements < 1 
src_is x #0 or 1 


Description: 

This routine calculates the mean of input: 
- 1. 
L= We, x{i) 
Notes: 


e The division result is rounded to the nearest integral value. 
e The sum is accumulated in 32 bits. If no_elements is more than a. overflow may occur. 
e Ifsrc_is _x is 1, data is located in X memory. 


If src_is_x is 0, data is located in Y memory. 
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8.8.14 Variance 


Definition: 
int Variance (long *variance, short *mean, const short input[ ], long no_elements, 
int src_is_x) 
Arguments: 
*variance pointer to the variance of input 
*mean pointer to mean of data 
input ] input x 
no_elements number of elements N 
src_is_X location specification of data 


Returns: int 
EDSP_OK success 


EDSP_BAD_ ARG no_elements < | 
src_is x#0or 1 


Description: 


This routine calculates the mean and variance of input: 


Notes: 


e The division results are rounded to the nearest integral values. 


e x is accumulated in 32 bits and is not checked for overflow. If no_elements is more than 2'°-1, 
overflow may occur. 


© © is accumulated in 63 bits and is not checked for overflow. 
e Ifsrc_is _x is 1, data is located in X memory. 


If src_is_x is 0, data is located in Y memory. 
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8.8.15 MaxI 


Definition: 

int MaxI (short **max_ptr, short input[ ], long no_elements, int src_is_x) 
Arguments: 

**max_ptr pointer to pointer to the maximum element 

input[ | input 

no_elements number of elements 

src_is_x location specification of data 


Returns: int 
EDSP_OK success 


EDSP_BAD_ ARG no_elements < | 
src_is x#0orl 


Description: 


This routine searches input to find the element with the maximum value, and returns its address in 
max_ptr. 


Notes: 


e If several elements have the same maximum value the one nearest the start of input is returned. 
e Ifsrc_is _x is 1, data is located in X memory. 


If src_is_x is 0, data is located in Y memory. 
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8.8.16 Minl 


Definition: 

int Minl (short **min_ptr, short input[ ], long no_elements, int src_is_x) 
Arguments: 

**min_ptr pointer to pointer to the minimum element 

input[ ] input 

no_elements number of elements 

src_1s_x location specification of data 


Returns: int 
EDSP_OK success 


EDSP_BAD_ARG no_elements < | 
src_is x #0or l 


Description: 


This routine searches input to find the element with the minimum value, and returns its address in 
min_ptr. 


Notes: 


e Ifseveral elements have the same minimum value the one nearest the start of input is returned. 
e Ifsrc_is _x is 1, data is located in X memory. 


If src_is_x is 0, data is located in Y memory. 
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8.8.17  PeakI 


Definition: 

int PeakI (short **peak_ptr, short input[ ], long no_elements, int src_is_x) 
Arguments: 

**neak_ptr pointer to pointer to the peak element 

input[ ] input 

no_elements number of elements 

src_is_X location specification of data 


Returns: int 
EDSP_OK success 


EDSP_BAD_ARG no_elements < 1 
src_is x#0or l 


Description: 


This routine searches input to find the element with the maximum absolute value, and returns its 
address in peak_ptr. 


Notes: 


e Ifseveral elements have the same peak value the one nearest the start of input is returned. 
e Ifsrc_is _x is 1, data is located in X memory. 


If src_is_x is 0, data is located in Y memory. 


Rev. 1.0, 09/98, page 410 of 476 


HITACHI 


Appendix A Compiler-Prescribed Language Specifications 
and Library Function Specifications 


A.l 


Language Specifications 


(1) Translation 


Table A.1_ Translation Specifications 
No. Item 
1 Error information on error detection 


(2) Environment 


Table A.2. Environment Specifications 
No. Item 
1 Purpose of actual argument for the "main" 


function 


Structure of interactive I/O devices 


(3) Identifiers 


Table A.3 


No. 
1 


Note: 


Identifier Specifications 


Item 


Number of valid letters in non externally-linked 
identifiers (internal names) 


Number of valid letters in externally-linked 
identifiers (external names) 


Distinction of uppercase and lowercase letters 


Compiler Specifications 


See section 4, Error Messages. 


Compiler Specifications 


Not stipulated 


Not stipulated 


Compiler Specifications 


Up to 250 letters in both external and 
internal names 


Uppercase and lowercase letters are 


in externally-linked identifiers (external names) distinguished 

Identifiers of which the first 250 characters are identical but that contain different characters 
from the 251st character are processed as identical identifiers. 

(a) longabcde...ab; (where the 250th character is "a" and the 251st character is "b) 

(b) longabcde...ac; (where the 250th character is "a" and the 251st character is "c") 


Identifiers (a) and (b) are identical up to the 250th character, and are therefore handled 
as the same identifier, even though they differ from the 251st character. 
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(4) Characters 


Table A.4 Character Specifications 


No. 


1 


Item 


Elements of source character sets and 
execution environment character sets 


Shift states used in coding multi-byte 
characters 


Number of bits in characters in character sets 
in program execution 


Relationship between source program 
character sets in character constants and 
string literals and characters in execution 
environment character sets 


Values of characters not stipulated in 
language specifications and integer character 
constants that include extended notation 


Values of character constants that include two 
or more characters, and wide character 
constants that include two or more multi-byte 
characters 


Compiler Specifications 


Source program character sets and 
execution environment character sets are 
both ASCII character sets. However, 
Japanese codes of the host environment 
can be used in source program 
comments and character strings. 


Shift states are not supported. 


8-bit 


Correspond to same ASCII characters 


Characters and extended notations not 
stipulated in the language specifications 
are not supported. 


The first four characters of character 
constants are valid for C compilation. The 
first character of character constants is 
valid for C++ compilation. Wide character 
constants are not supported. Note that a 
warning error message is output if you 
specify more than one character. 


Specifications of locale used for converting 
multi-byte characters to wide characters 


Do simple char types have the same value 
range as signed char or unsigned char types? 


Rev. 1.0, 09/98, page 412 of 476 


locale is not supported. 


Same value range as signed char types. 


HITACHI 


(5) Integers 


Table A.5 Integer Specifications 


No. Item 
1 Representation and values of integers 
2 Values of integers when converted to shorter 


signed integer types or converted to values 
that cannot be represented by signed 
character types (when converted values 
cannot be represented by the target type) 


3 Result of bit-wise operations on signed 
integers 


Remainder sign in integer division 


Result of right shift of signed integral types 
with a negative value 


Table A.6 Range of Integer Types and Values 


Compiler Specifications 


See table A.6. 
(Negative numbers are represented using 
2's complements.) 


The least significant two bytes or least 
significant one byte of the integer value 
are the post-conversion value. 


Signed value 


Same sign as dividend 


Maintains sign bit 


No. Type Value Range Data Size 
1 char (signed char) —128 to 127 1 byte 

2 unsigned char 0 to 255 1 byte 

3 short —32768 to 32767 2 bytes 

4 unsigned short 0 to 65535 2 bytes 

5 int —2147483648 to 2147483647 4 bytes 

6 unsigned int 0 to 4294967295 4 bytes 

t long —2147483648 to 2147483647 4 bytes 

8 unsigned long 0 to 4294967295 4 bytes 


Note: Type specifiers in parentheses are optional. The order in which types are specified is not 


stipulated. 


Rev. 1.0, 09/98, page 413 of 476 


HITACHI 


(6) Floating Point Numbers 


Table A.7 Floating Point Number Specifications 


No. Item Compiler Specifications 
1 Representation and values of floating-point There are three types of floating point 
type numbers: float, double, and long double 


types. See section A.3, Floating Point 
Number Specifications, for the internal 
representation of floating point types and 
specifications for their conversion and 


2 Method of truncation when integers are 
converted into floating point numbers that 
cannot accurately represent the actual value 


3 Methods of truncation or rounding when operation. Table A.8 shows the limits of 
floating point numbers are converted into floating point type values that can be 
shorter floating point numbers expressed. 


Table A.8 Limits of Floating Point Number Values 1 


Limits 
No. Item Decimal notation*" Hexadecimal notation 
1 Maximum value of float type 3.4028235677973364e+38f TE 7 FFF 
(3.4028234663852886e+38f) 
2 Minimum positive value of float 7.0064923216240862e—46f 00000001 
type (1.4012984643248171e-45f) 
3 Maximum values of double* 1.7976931348623158e+308 7 fe fff ffTTTfffff 
type and long double type (1.7976931348623157e+308) 
4 Minimum positive values of 4.9406564584 124655e-324 0000000000000001 
double*’ type and long double (4.9406564584124654e-324) 
type 
Notes: 1. The limit for decimal notation is 0 or infinity. Values in parentheses are theoretical 
values. 


2. When the -double = float option is specified, double types are the same value as float 
types. When the -fpu=single option is specified, double and long doulbe types are the 
same value as float types. When the -fpu = double option is specified, float types are 
the same value as double types. 
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(7) Arrays and Pointers 


Table A.9 Array and Pointer Specifications 


No. Item Compiler Specifications 
1 Integer type (size_t) required to hold maximum unsigned long type 
array size 
Zz Conversion from pointer type to integer type _—_—- Value of least significant byte of pointer 


(pointer type size >= integer type size) 


3 Conversion from pointer type to integer type 
(pointer type size < integer type size) 


4 Conversion from integer type to pointer type 
(integer type size >= pointer type size) 


5 Conversion from integer type to pointer type 
(integer type size < pointer type size) 

6 Integer type (ptrdiff_t) required to hold 
difference between pointers to members in the 
same array 


(8) Registers 


Table A.10 Register Specifications 


No. Item 


1 Maximum number of register variables that 
can be assigned to registers 


2 Types of register variables that can be 
assigned to registers 


type 
Sign extension 


Value of least significant byte of integer 
type 
Sign extension 


int type 


Compiler Specifications 
7 


char, unsigned char, signed char, bool 
short, unsigned short, 

int, unsigned int, 

long, unsigned long, 

float, pointer 


Rev. 1.0, 09/98, page 415 of 476 


HITACHI 


(9) Structures, Unions, Enumeration Types, and Bit Fields 


Table A.11 Structure, Union, Enumeration Types, and Bit Field Specifications 


No. Item Compiler Specifications 

1 Referencing members in union type accessed Can be referenced but value cannot be 
by members of another type guaranteed 

2 Boundary alignment of structure members The maximum data size in a structure 


member is the value of the boundary 
alignment. See table A.6, Range of 
Integer Types and Values. —" 


Sign of bit fields of simple int types signed int type 
Order of bit fields within int type size Assigned from most significant bit *” 
5 Method of assignation when the size of abit | Assigned to next int type area. ** 


field assigned after a bit field is assigned 
within an int type size exceeds the remaining 
size in the int type 


6 Permissible type specifiers in bit fields char, unsigned char, signed char, short, 
unsigned short, int, unsigned int, long, 
unsigned long type 


7 Value of integer representing value of int type 
enumeration type 


Notes: 1. For details of assignment of structure members, see 2.2.2 (2), Structures/Class Types, 
in section 2, C/C++ Programming. 


2. For details of assignment of bit fields, see 2.2.2(3), Bit Fields, in section 2, C/C++ 
Programming. 


(10) Modifiers 


Table A.12 Modifier Specifications 


No. Item Compiler Specifications 


1 Types of volatile data access Not stipulated 
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(11) Declarations 


Table A.13 Declaration Specifications 


No. Item Compiler Specifications 


1 Number of types (pointer types, array types, 16 max. 
function types) qualifying basic types 


(a) The following is an example of counting the number of types modifying basic types. 


i. int a; Here, a is an int type (basic type) and the number of declarators qualifying the 
basic type is 0. 


ii. char *f(); Here, f is a function returning a pointer type to a char type (basic type), and 
the number of declarators qualifying the basic type is 2. 


(12) Statements 
Table A.14 Statement Specifications 
No. Item Compiler Specifications 


1 Number of case labels that can be declared in 511 max. 
one switch statement 
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(13) Preprocessor 


Table A.15 Preprocessor Specifications 


No. 


1 


6 


Note: 


Item 


Relationship between single-character 


character constants in constant expressions in 
a conditional compile, and character sets in 


the execution environment 


Method of reading include files 


Support for include files enclosed in double 


quotation marks 


Space characters in character strings after 


expansion when character strings of real value 
parameters in a #define statement are space 


characters 


Operation of #pragma statements 


DATE_ and _TIME_ value 


Compiler Specifications 


Preprocessor statement character 
constants are the same as the execution 
environment character set. 


Files enclosed in "<" and ">" are read 
from the directory specified in the include 
option. When multiple directories are 
specified, they are searched in the order 
specified. If the specified file is not found, 
the directory specified in environment 
variable SHC_INC is searched, followed 
by the system directory (SCH_LIB). 


Supported. Include files are read from the 
current directory. If not found in the 
current directory, the file is searched for 
as described in 2, above. 


Space character strings are expanded as 
one space character. 


The following are supported’: 
#pragma interrupt 
#pragma section 
#pragma inline 
#pragma inline_asm 
#pragma abs16 
#pragma gbr_base 
#pragma gbr_base1 
#pragma noregsave 
#pragma noregalloc 
#pragma regsave 
#pragma global_register 
#pragma pack1 
#pragma unpack 


A value is specified based on the host 
machine's timer at the start of compiling. 


See section 2.3, Extended Functions, for #pragma specifications. 
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A.2 Library Function Specifications 


This section describes the specifications of compiler-defined library functions not stipulated in the 
language specifications. 


(1) stddef.h 


Table A.16 stddef.h Specifications 


No. Item Compiler Specifications 
1 Macro NULL value Value is 0 in pointer to void type (C 
compilation). 


Value is 0 (C++ compilation) 
2 prtdiff_t content int type 


(2) assert.h 


Table A.17 assert.h Specifications 


No. Item Compiler Specifications 


1 Data output by assert function, and aborting Output format is shown under (a). On 
completion of outputting the data, the 
abort function is called and operation is 
aborted. 


(a) Ifthe value of an assert expression is 0, the following message is output. 


Assertion failed: A<expression>AFileA<filename>, LineA<line_number> 


(3) ctype.h 


Table A.18 ctype.h Specifications 


No. Type Compiler Specifications 


1 Character sets checked by isalnum, isalpha, | Character sets that can be represented 
iscntrl, islower, isprint, and isupper functions — by unsigned char types. Table A.19 
shows the characters that are true as a 
result of a check. 
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Table A.19 Sets of True Characters 


No. 


Oya; Rl_wo!;n] — 


Function Name 
isalnum 

isalpha 

iscntrl 

islower 

isprint 

issupper 


(4) math.h 


Table A.20 math.h Specifications 


No. 


1 


Item 


Value returned by math function when input 
parameter exceeds permissible value range 


Whether value of macro ERANGE is set to 
errno when a math function underflow error 
occurs 


function is 0 


True Characters 

‘0’ to ‘9’, ‘A’ to ‘Z’, ‘a’ to ‘2’ 
‘A’ to ‘2’, ‘a’ to ‘2’ 

‘\x00’ to ‘\x1f, \x7f 

‘a’ to ‘2’ 

‘\x20’ to ‘\x7E’ 

‘A’ to ‘2’ 


Compiler Specifications 


Returns a not-a-number. See section A.3, 
Floating Point Number Specifications, for 
the format of not-a-number. 


Not set 


Operation when second parameter of fmod 


Returns a not-a-number and a range 


error OCCUrs. 


math.h includes definitions for the ENUM and ERANGE macros, which show the values of 
library error numbers. 


(5) setjmp.h 


Table A.21  setjmp.h Specifications 


No. 


1 


Item 


Context in programs that permit setjmp 
function to be called 


Specifications for setimp_a() and longjmp_a() 


Compiler Specifications 


Guaranteed in standalone statements in 
setjmp() or ver=setjmp() format, 
expressions that indicate the conditions 
in if, while, do, or for statements, and 
when specified in switch or return 
statements 


With the SH-4 CPU, environment 
including floating point extension register 


values are saved and restored. 
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(6) 


stdio.h 


Table A.22_ stdio.h Specifications 


No. Item Compiler Specifications 

1 Requirement for new line character to show ___ Not stipulated. Conforms to low-level 

that last line of input text is the end interface routine specifications. 

2 Whether space character immediately 

preceding newline character is fetched when 
text is read 

3 Number of null characters added to data in 

binary files 

4 Initial value of file position pointer when in add 

mode 

5 Whether subsequent data is lost from a file 

when text is output to a text 

6 Specifications for file buffering 

i Whether a 0-length file exists 

8 File naming rules 

9 Whether a file can be opened when already 

open 
10 Output format of %p format conversion by Hexadecimal output 
fprintf function 
11 Input format of %p format conversion in fscanf Hexadecimal input. 
function When it is not at the start, end, or 
Meaning of hyphen (-) in fscanf function immediately after '"*", the hyphen shows 
the range from the immediately preceding 
character to the following. 

12 Value of errno set in fgetpos and ftell functions The fgetpos function is not supported. 
There are no stipulations pertaining to the 
ftell function. Conforms to low-level 
interface routine specifications. 

13 Output format of messages generated by The message output format is shown in 

perror function (a). 
14 Operation when size in calloc, malloc, and Allocation of 0-byte area. 


realloc functions is 0 


(a) perror function output format is as follows: 


<character string>: <error message corresponding to error No. set in error> 


(b) Table A.23 shows the format for showing infinity and not-a-number in floating point 
numbers in printf and fprintf functions. 


Rev. 1.0, 09/98, page 421 of 476 
HITACHI 


Table A.23 Format of Infinity and Not-a-Number 


No. Item 
1 Positive infinity 
Negative infinity 


Not-a-number 


(7) string.h 


Table A.24  string.h Specifications 


No. Item 


1 Sign of values returned by processing of 
memcmp, strcmp, and strncmp functions 


2 Contents of error messages returned by 
strerror function 
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+4444 


Compiler Specifications 


Processed as signed values 


See section 4.2, Standard Library Error 
Messages. 
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(8) errno.h 


Table A.25 errno.h Specifications 


No. 


errno The error no. is an int type variable. It is 


Item Compiler Specifications 


set when an error occurs in a library 
function. 


ERANGE See section 4.2, Standard Library Error 


EDOM - Messages. 


EDIV 
ESTRN 
PTRERR 
ECBASE 
ETLN 
EEXP 
EEXPN 
EFLOATO 
EFLOATU 
EDBLO 
EDBLU 
ELDBLO 
ELDBLU 
NOTOPN 
EBADF 


ECSPEC 
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(9) Unsupported Libraries 


Table A.26 lists the libraries not supported by this compiler. Note, however, that the header files 
themselves of signal.h and time.h are not supported. 


Table A.26 Unsupported Libraries 


No. Header File Library Function Name 

1 signal.h signal, raise 

2 stdio.h remove, rename, tmpfile, tmpnam 
3 stdlib.h getenv, system 

4 time.h clock, difftime, time, asctime, ctime, 


gmtime, localtime 
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A.3 Floating Point Number Specifications 


(1) Internal Representation of Floating Point Numbers 
Floating point numbers handled by this compiler are internally represented in the standard 
IEEE format. This section outlines the internal representation of floating point numbers in the 
IEEE format. 
(a) Format for internal representation 
float types are represented in the IEEE single-precision (32-bit) format, while double types 
and long double types are represented in the IEEE double-precision (64-bit) format. 
(b) Structure of internal representation 
Figure A.1 shows the structure of the internal representation of float, double, and long 
double types. 


float type” 
31 30 23 22 0 


wi Exponent (8 bits) Mantissa (23 bits) 


Sign (1 bit) 


double type and long double type 
63 62 52 51 0 


wi Exponent (11 bits) Mantissa (52 bits) 


Sign (1 bit) 

When the -double=float option is specified, double types are internally represented in the 
same format as float types. When the -cpu=sh4 and -fpu=single options are specified, 
double types and long double types are internally represented in the same format as float 
types. When option -cpu=sh4 and option -fpu=double are specified, float types are internally 
represented in the same format as double types. 


Figure A.1 Structure of Internal Representation of Floating Point Numbers 
The internal representation format consists of the following parts: 


i. Sign 
Shows the sign of the floating point number. 0 is positive, 1 is negative. 
il. Exponent 
Shows the exponent of the floating point number to the power of 2 
ili. Mantissa 
Shows the data corresponding to the valid numerals of the floating point number 
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(c) Types of represented values 


In addition to the normal real numbers, floating point numbers can also represent values 
such as infinity. The following describes the types of values represented by floating point 
numbers. 


i. Normalized numbers 
When the exponent is 0 or not all bits are 1. Represents normal real values. 
ii. Denormalized numbers 


When the exponent is 0 and the mantissa is other than 0. Represents real values having 
small absolute numbers. 


ill. Zero 

When the exponent and mantissa are 0. Represents the value 0.0. 
iv. Infinity 

When all bits of the exponent are 1 and the mantissa is 0. Represents infinity. 
v. Not-a-number 


When all bits of the exponents are | and the mantissa is other than 0. Represents the 
result of operation such as "0.0/0.0", "oo/co", "oo-co", which does not correspond to a 
number or infinity. 


Note: Denormalized numbers are floating point numbers of small absolute values that are 


outside the range that can be represented by normalized numbers. There are fewer valid 
digits than in normalized numbers. Therefore, if the result or intermediate result of a 
calculation is a denormalized number, the number of valid digits in the result cannot be 
guaranteed. When the CPU is an SH-4, denormalized numbers are processed as 0 when 
option -denormalize=off is specified. When -denormalize=on is specified, denormalized 
numbers are processed as denormalized numbers. 


Table A.27 Types of Values Represented as Floating Point Numbers 


Exponent 

Mantissa 0  — Qornotallbitsare1 Allbitsare1 
0 Normalized number Infinity 

Other than 0 Denormalized number Not-a-number 
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(2) float type 
float types are internally represented as a 1-bit sign, 8-bit exponent, and 23-bit mantissa. 


i. 


Normalized numbers 


The sign indicates the sign of the value, either 0 (positive) or | (negative). The exponent is 
between | and 254(2°—2). The actual exponent is gained by subtracting 127 from this 
value. The range is between —126 and 127. The mantissa is between 0 and 2%-1. The 
actual mantissa is interpreted as the value of which the 2”rd bit is 1 and this is followed by 
the decimal point. Values of normalized numbers are as follows: 


(—1)8" x 2°Pore"""127 ¢ (14+ (mantissa) x 27) 


Example: 


31 30 23 22 0 


11]10000000 1100000000000000000000 


Sign: — 

Exponent: 10000000(2)— 127 = 1, where (2) indicates binary 
Mantissa: 1.11lq@) = 1.75 

Value: —1.75x2' = -3.5 


Denormalized numbers 


The sign indicates the sign of the value, either 0 (positive) or 1 (negative). The exponent is 
0 and the actual exponent is —126. The mantissa is between 1 and 2”°—1, and the actual 
mantissa is interpreted as the value of which the 2”’rd bit is 0 and this is followed by the 
decimal point. Values of denormalized numbers are as follows: 

(—1)8" x 2exPonent=126 (mantissa) x 2) 


Example: 


31 30 23 22 0 


[0}00000000 1100000000000000000000 


Sign: a 

Exponent: 0-126 = —126 

Mantissa: 0.11) = 0.75, where (2) indicates binary 
Value: 0.75 x 2"° 
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ili. Zero 
The sign is 0 (positive) or | (negative), indicating +0.0 or —0.0, respectively. The exponent 
and mantissa are both 0. 


+0.0 and —0.0 are both the value 0.0. See section A.3 (4), Floating Point Operation 
Specifications, for the functional differences deriving from the sign used with zero. 


iv. Infinity 
The sign is 0 (positive) or 1 (negative), indicating +ce or —ce, respectively. 
The exponent is 255(2°-1). 


The mantissa is 0. 


v. Not-a-number 
The exponent is 255(2*-1). 


The mantissa is a value other than 0. 


Note: When the CPU is SH2E, SH3E, or SH4, not-a-number is called a gNaN when the MSB of 
the mantissa is 0, or sNaN when the MSB of the mantissa is 1. There are no stipulations 
regarding the values of other mantissa fields or the sign. 


(3) double types and long double types 


double types and long double types are internally represented as a 1-bit sign, 11-bit exponent, 
and 52-bit mantissa. 


i. Normalized numbers 
The sign indicates the sign of the value, either 0 (positive) or 1 (negative). The exponent is 
between 1 and 2046(2''—2). The actual exponent is gained by subtracting 1023 from this 
value. The range is between —1022 and 1023. The mantissa is between 0 and 2°"—1. The 
actual mantissa is interpreted as the value of which the 2°°nd bit is 1 and this is followed by 
the decimal point. Values of normalized numbers are as follows: 


2 x gexponent—1023 x (1+(mantissa) x ions 


Example: 


63 62 52 51 0 


Jolo141111141414]11410000000000000000000000000000000000000000000000000 


Sign: + 

Exponent: 1111111111()—-1023 = 1, where () indicates binary 
Mantissa: 1.111() = 1.875 

Value:  -1.875 x 2° = 1.875 
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il. 


Denormalized numbers 

The sign indicates the sign of the value, either 0 (positive) or 1 (negative). The exponent is 
0 and the actual exponent is -1022. The mantissa is between 1 and 2°*-1, and the actual 
mantissa is interpreted as the value of which the 2”’rd bit is 0 and this is followed by the 
decimal point. Values of denormalized numbers are as follows: 

(-1)8" x 2°P"""_ 1022 x ((mantissa) x 2°”) 


Example: 


63 62 52 51 0 


}o|0.0000000000|1110000000000000000000000000000000000000000000000000 


ill. 


Note: 


Sign: - 

Exponent: 02) -1022 = —1022, where (2) indicates binary 
Mantissa: 0.111.) = 0.875 

Value: 0.875 x 2°” = 1.875 


Zero 

The sign is 0 (positive) or 1 (negative), indicating +0.0 or —0.0, respectively. The exponent 
and mantissa are both 0. 

+0.0 and —0.0 are both the value 0.0. See section A.3(4), Floating Point Operation 
Specifications, for the functional differences deriving from the sign used with zero. 


. Infinity 


The sign is 0 (positive) or 1 (negative), indicating +oo or —ce, respectively. The exponent is 
2047(2''-1). 
The mantissa is 0. 


Not-a-number 
The exponent is 2047(2''—1). 
The mantissa is a value other than 0. 


When the CPU is SH-2E, SH-3E, or SH-4, not-a-number is called a qNaN when the MSB 
of the mantissa is 0, or sNaN when the MSB of the mantissa is 1. There are no stipulations 
regarding the values of other mantissa fields or the sign. 
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(4) Floating Point Operation Specifications 
This section describes the specifications for arithmetic operations on floating point numbers in 
C, and for converting between the decimal representation of floating point numbers and their 
internal representation during compiling and in library processing. 


(a) Specifications for arithmetic operations 


1. 


ill. 


je’ 


Rounding of results 

When the result of arithmetic operations on floating point numbers exceeds the number 

of valid limit in the mantissa in internal representation, the result is rounded according 

to the following rules: 

a. The result is rounded toward the closer of the two internal representations of the 
approximating floating point numbers. 

b. When the result is exactly between the two approximating floating point numbers, it 
is rounded to the floating point number of which the last digit of the mantissa is 0. 

c. When the CPU is SH-2E or SH-3E, the portion that exceeds the valid digits is 
truncated. 

d. When the CPU is SH-4, and the -round = nearest option is specified, the portion that 
exceeds the valid digits is rounded to the nearest value. When the -round = zero 
option is specified, the portion that exceeds the valid digits is rounded toward zero. 


Processing of overflows, underflows, and illegal operations 

The following is performed in the event of an overflow, underflow, or illegal operation. 

a. In the case of an overflow, the result is a positive or negative infinity, depending on 
the sign of the result. 

b. In the case of an underflow, the result is a positive or negative zero, depending on 
the sign of the result. 

c. In the case of an illegal operation such as, when infinity values of the opposite sign 
have been added, when an infinity has been subtracted from another infinity of the 
same sign, when zero has been multiplied by infinity, zero is divided by zero, or 
infinity is divided by infinity, the result is a not-a-number. 

d. When an overflow results from converting a floating point number to an integer, 

the result is not guaranteed. 

Note: Operations are performed on constant expressions during compiling. When an 

overflow, underflow, or illegal operation then occurs, a warning level error 
message is output. 


Notes on operations on special values 


The following are notes on operations on special values (zero, infinity, and not-a- 
number). 


a. The sum ofa positive zero plus negative zero is a positive zero. 


b. The difference between two zeros of the same sign is a positive zero. 
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The result of operations that include not-a-number in one or both operands is always 
a not-a-number. 


In comparative operations, positive zeros and negative zeros are processed as equal. 


The result of comparative operations or equivalence operations where either one or 
both operands are not-a-number is true for "!=" and false in all other cases. 


(b) Conversion between decimal and internal representation 


This section describes the specifications for conversions between floating point numbers in 


a source program and internal representation, and conversion by library functions between 
the decimal representation of floating point numbers in ASCII character strings and their 
internal representation. 


i, 


il. 


When converting from decimal to internal representation, the decimal value is first 
converted to its normalized form. The normalized form of a decimal value is 
"+M x 10°“", where M and N are in the following range: 


a. Normalized form of float types 


0<M<107-1 

O0O<NS99 

Normalized form of double and long double types 
0<M<10'7-1 

0<N<999 


If a decimal value cannot be converted to its normalized form, an overflow or 
underflow occurs. If the decimal representation contains more valid numerals than 
the normalized form, the trailing digits are truncated. In this case, a warning level 
error message is output when compiling and the corresponding error number is set 
in errno when the program is executed. For conversion to its normalized form, the 
original decimal representation must, in the form of an ASCII character string, be 
within 511 characters. If not, an error occurs when compiling and the corresponding 
error number is set in errno when the program is executed. When converting from 
internal representation to decimal, the value is first converted to the normalized 
decimal form, then converted to an ASCII character string according to the 
specified format. 


Conversion between normalized form of decimals and internal representation 

When converting from the normalized form of decimals to internal representation, and 
vice versa, errors cannot, because of processing efficiency, be avoided when the 
exponent is large or small. The following describes the range within which conversion 
is accurate, and the error limits when the values are outside that range. 


a. Range for accurate conversion 


The rounding shown in (a)(i), "Rounding of results" is correctly applied for floating 
point numbers within the ranges shown below. No overflow or underflow will occur 
within these ranges. 
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(1) float types:0<M<107-1,0<N<13 
(2) double and long double types: 0 < M< 10'"-1,0<N< 27 

b. Error limits 
The difference between the error when converting values that do not fall in the 
ranges shown in a. and the error that occurs when rounding is correctly performed 
does not exceed 0.47 times the smallest digit of the valid numerals. If the ranges 
shown in a. are exceeded, an overflow or underflow may occur during conversion. 
In this case, a warning level error message is output when compiling, and the 
corresponding error number is set in errno when the program is executed. 
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Appendix B_ Examples of Assigning Arguments 


Example 1 Arguments in the type for passing to registers are assigned, in the order in which 
they are declared, to registers R4 to R7. 


int £(char,short,int,float) ; R4 Not guaranteed 
: R5_ | Not guaranteed 


£(1,2,3;4.0) 3 R6 


R7 


Example 2 Arguments that cannot be assigned to registers are assigned to the stack. Or, when 
the arguments are (unsigned) char or (unsigned) short types and are assigned to the 
argument area in the stack, they are first extended to 4 bytes. 


int f(int,short,long,float,char) ; R4 
: 
. 


TLow address 


uc) 
stacks Not guaranteed 5 


JHigh address 


Example 3. Arguments of types that cannot be assigned to registers are assigned to the stack. 


struct s{int x,y; }a; R4 1 
int £(int,struct s,int) ; R5 3 


f(1,a,3); TLow address 
Argument area 
sc 


High address 
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Example 4 When declared in a prototype declaration as a function with a variable number of 
arguments, the arguments without corresponding types and the immediately 
preceding arguments are assigned to the stack in the order in which they are 
declared. 


£(1.0,2,3,4); TLow address 


(stack) 


JHigh address 


Example 5 When the type returned by a function is more than 4 bytes, or a class, the return 
value address is set immediately before the argument area. If the size of the class is 
not a multiple of 4 bytes, unused space results. 


struct s{char x,y,z; }a; Argument area Return value address 
double f(struct s); (stack) Unused 
‘ a.x ay aZ | snace 
f(a); 


TLow address 


Area for setting return value 


High address 
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Example 6 When the CPU is SH2E or SH3E, float type arguments are assigned to the FPU 
registers. 


int f(char,float,short,float,double); R4 
R5 
£ (1.2.0, 3 4.0, 5.10) 3 R6 
R7 


TLow address 
Argument area 50 
(stack) 


High address 


Example 7 When the CPU is SH4 and option -fpu is not specified, float and double type 
arguments are assigned to the FPU registers. 


int £(char,float,double,float,short) ; FR4(DR4) 
FR5 

£ (4,2) ..0 4. 0,5 0, 3) ; FR6(DR6) 
FR7 
FR8(DR8) 


FRIO(ORI0) 


TLow address 
“a 
(stack) 


High address 


R4 
R5 
R6 
R7 
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Appendix C Using Registers and Stack Areas 


This section describes how the compiler uses registers and stack areas. Registers and stack areas in 
functions are controlled by the compiler and the user is not required to have any particular 
understanding of how these areas are used. Figure C.1 shows how the register and stack areas are 


used. 


FR10 (DRI G} 
FR14 
FR1i2 (DRI 2) 


FR13 


FRO to FRI5: 
(DRO) (DR14) 
FR4 to FR11: 
(DRa} (DRio) 


(SHE, SHSE, SH4 only) 


Stack 


Frorvanaaies [Bae 


For variables and temporary storage Roto Rid: Forvanables and temporary storage 
fnemedate results of operators) fnitemneadate results of operations) 
For storing arguments. Indicated by [EEE]. RéatoR?: Forstonng anguments. Indicated by [ FEEEEa). 


Figure C.1 Using Register and Stack Areas 
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Appendix D Examples of Creating Termination Processing 
Functions 


D.1 Examples of Creating the Termination Processing Registration and 
Execution (onexit) Routine 


This section shows an example of creating the library onexit function that registers termination 
processing. 


The onexit function registers the addresses of the functions that were passed as parameters in the 
termination processing table. When the number of functions that have been registered exceeds the 
limit value (in this example, up to 32 functions can be registered) or the same function is 
registered twice or more, the onexit function returns NULL as the return value. Otherwise, the 
function returns a value other than NULL (in this example, the address of the function that was 
registered). 


See below for the program example. 


Example 


#include <stdlib.h> 
typedef void *onexit_t; 


int _onexit_count = 0; 
onexit_t(*_onexit_buf[32]) (void) ; 


extern onexit_t onexit(onexit_t (*) (void)); 
onexit_t onexit (f) 


onexit_t (*£) (void); 


{ 


int i; 
for( i = 0; i < _onexit_count; i++ ) 
if( _onexit_buf[i] == f) /*Checks if the function has already been */ 


/*registered.*/ 
return NULL; 
if( onexit count == 32) /*Checks if the number of functions has */ 
/*reached the limit value.*/ 
return NULL; 
else { 
onexit buf[ _onexit count] = £;/*Registers the address of the function.*/ 


_onexit_count++; 
return & onexit buf[ onexit count - 1]; 
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D.2 Example of Creating the Program Termination (exit) Routine 


This section shows an example of creating the library exit function that performs program 
termination processing. Since program termination processing varies according to the user 
system, create termination processing according to the specification of the user system, using the 
program shown below as the guideline. 


The exit function performs program termination processing of a C program according to the 
termination code of the program that was passed as the parameter, and resets the environment to 
that at program activation. This function sets the termination code in the external variable and 
resets the environment to that saved by the setjmp function immediately before the main function 
was called. 


See below for the program example. 


#include <setjmp.h> 


#include <stddef.h> 


typedef void *onexit _t; 
extern int _onexit count; 


extern onexit_t (*_onexit_buf[32]) (void) ; 


extern jmp_buf _init_env; 


extern int _exit_code; 


extern void _CLOSEALL() ; 


extern void exit(int); 


void exit( code ) 


int code; 

int i; 

_exit_code = code; /*Sets the return code in the _exit_code.*/ 

for (1 = _onexit count+1; 1 > O07 i--) 

(*_onexit_buf[i]) (); /*Executes the functions that were registered */ 

/*by the onexit function sequentially.*/ 

_CLOSEALL () ; /*Closes all the functions that were opened. */ 
longjmp(_init env, 1); /*Resets the environment to the environment 


/*that was saved by setjmp.*/ 
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Note: To reset the environment to that before program execution in the above function, create 
the following function "callmain" and call the function "callmain" instead of calling the 
function "main" from the initialization routine "init". 


#include <setjmp.h> 
jmp buf init env; 
int _exit code; 


void callmain() 
/*Save the current environment by using setjmp and call */ 
/*the main function.*/ 
/*When control is returned from the exit function, */ 


/*the processing is terminated.*/ 
if (!setjmp(_init_env) ) 


_exit_code = main() ; 


D.3 Example of Creating the Abnormal Termination (abort) Routine 


At abnormal termination, execute program abnormal termination processing according to the 
specification of the current user system. 


See the following example of the program that outputs a message to the standard output device, 
closes the function, and waits for resetting in unlimited loop. 


Example 
#include <stdio.h> 
extern void abort(); 


extern void _CLOSEALL () ; 


void abort () 


{ 
printf ("program is abort !!\n"); /*Outputs a message*/ 
_CLOSEALL () ; /*Closes the file*/ 
while(1); /*Unlimited loop*/ 

} 
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Appendix E Example of Creating Low-Level Interface 
Routines 


[RR RR RR RR RR KKK IRR KOKI RIOR RR IR IR IR KR IR A ke / 


/* lowsrc.c: */ 
/* a a a a ae a ES: NES SERIES St RA RENE eS RIES ae RRS ee esl eNEN EN er ese eh pelle Ses */ 
/* SH Series simulator debugger interface routine * / 
/* Supports the standard input and output only */ 
/* (stdin, stdout, and stderr) */ 


[BR RR I RI RI RR I RR TO I IR IR KO IR IR KR KO IR IO KK KR I kk  / 


#include <string.h> 


/* File number */ 


#define STDIN 0 /*Standard input (console) */ 
#define STDOUT 1 /*Standard output (console) */ 
#define STDERR 2 /*Standard error output (console) */ 
#define FLMIN ) /*Minimum file number */ 

#define FLMAX 3 /*Maxim number of files*/ 


/*File flag*/ 


#define O RDONLY 0x0001 /* Read Only *x/ 
#define O WRONLY 0x0002 /* Write Only */ 
#define O RDWR 0x0004 /* Read and Write*/ 


/* Special character code */ 
#define CR 0x0d /* Return * / 
#define LF 0Ox0a /* Line feed */ 


/*Area size that is managed by sbrk*/ 


#define HEAPSIZE 1024 
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[BRK RR RR KK KK KR RR KK KR KK RK IK KR KR KR RRR RK KR AK KK / 


/* Reference function declaration * / 
/* Reference of the assembly program that inputs and outputs * / 
/* characters to the console through the simulator debugger. */ 


[BR RR RK RR RR KK KK RR KR RR RR KR RR RR RR KK RR KK / 


extern void charput (char) ; /*Single character input processing*/ 


extern char charget (void) ; /*Single character output processing*/ 


[RRR RRR RRR RR RK KR KKK KKK KK KR KR KK KK KK RRR KKK RK KK KR RK KR KK RK KK RRR RK RRR RK / 


/* Definition of static variables */ 
/* Definition of the static variables that are used by the low * / 
/* standard interface routine */ 


[BR RRR RK RR KK KR KR KR KKK ROR KR KR KOR RR I RAK AO AK ee / 


char flmod[FLMAX] ; /* Mode setting location of the file that was opened */ 


static union { 
long dummy; /*Dummy to set a 4-byte boundary*/ 
char heap [HEAPSIZE] ; /*Declaration of the area that is managed by sbrk*/ 


} heap_area ; 


static char *brk=(char*)&heap_area; /* End address of the area * / 


/* assigned by sbrk */ 


[BRR KR RK KK I KK KR ROR I RR RO IA RK IR KR KR RK RK / 


ge open: Opens a file ey 
/* Return value: File number (successful) */ 
/* -1 (failed) * / 
[BORK KR KR KK KK RR KR RR RR RR RR RR RR RR RR KR RR KR RK KK / 
int open(char *name, /*File name*/ 

int mode) /*File mode*/ 
{ /*Checks the mode according to the file name and returns the file number*/ 

if (strcmp (name, "stdin") ==0) { /*Standard input file*/ 


i£((mode & O RDONLY) ==0) 
return. =1; 


£f1lmod [STDIN] =mode; 
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return STDIN; 


else if (strcmp (name, "stdout") ==0) { /*Standard output file*/ 
if ((mode & O WRONLY) ==0) 
return -1; 
£1lmod [STDOUT] =mode; 
return STDOUT; 


} 


else if (strcmp (name, "stderr") ==0) { /*Standard error output file*/ 
if ((mode & O WRONLY) ==0) 
return -1; 
£1lmod [STDERR] =mode ; 
return STDERR; 
} 
else 


return -1; /*Error* / 


[BR RR RR I IRR IRR RII RRR RRR RII I ARR RRA AOR AR ek / 


/* close: Closes a file */ 
/* Return value: 0 (successful) * / 
/* -1 (failed) * / 


[BR RR KK KK KK KK KK KK KK KR KK KK KK I RK AOR A RR KR AR RO / 


int close(int fileno) /*File number*/ 


{ 


if (fileno<FLMIN || FLMAX<fileno) /*Checks the file number range.*/ 


return -1; 


flmod[fileno] =0; /*Resets the file mode.*/ 


return 0; 
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[RR RR RR KK RK KR RR RK RR RK RR KK / 


/* read: Reads data */ 
/* Return value: Number of characters that have been read (successful) */ 
/* -1 (failed) */ 
[RRR RK RR RR RK RR KR RR RRR RR RR RR RR RR RRR RR KR RR RK RK RR KK KK / 
int read(int fileno, /*File number* / 

char *buf, /*Transfer destination buffer address*/ 


unsigned int count) /*Number of characters that have been read*/ 
unsigned int i; 
/*Checks the mode according to the file name and inputs the characters */ 


/*one by one to store them in buffer.*/ 


if (£lmod[fileno] & O _RDONLY || flmod[fileno] &O RDWR) { 
for(i=count; i>0; i--) { 
*buf=charget () ; 
if (*buf==CR) 
*buf=LF; 
buf++; 


} 


return count; 


} 


else 


return -1; 


} 


[RRR RRR I RR FR I IR RR RO FR I RRR KR IR RR a  / 


/* write: Writes data * / 
/* Return value: Number of characters that have been written * / 
/* -1 (failed) */ 
[8 IRR RR RR RR RR A RR KK RK RR KR RR RR RR RR RR KK / 
int write(int fileno, /*File number*/ 

char *buf, /*Transfer source buffer address*/ 


unsigned int count) /*Number of characters that have been */ 
/*written*/ 
unsigned int i; 


char c; 
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/*Checks the mode according to the file name and outputs the characters */ 


/*one by one.*/ 


if (£lmod[fileno] & O_WRONLY || flmod[fileno] & O RDWR) { 
for(i=count; i>0; i--) { 
c=*buf++; 


charput (c) ; 


} 


return count; 


[8 RR RII IRI RR IRI I IR IRI IORI I ARI ICRI II IR I IO A kk kk / 


/* lseek: Sets the file read/write position * / 
/* Return value: Offset from the read/write position from */ 
/* start of the file (successful) */ 
/* -1 (failed) */ 
/* (lseek is not supported by console input/output) * / 


[HR KK KK I IKK KK I I I IIR ACR IOI RA I I ee / 


long lseek(int fileno, /*File number*/ 
long offset, /*Read/Write position*/ 


int base) /*Offset starting point*/ 


return -1; 


[BR RK KR RR KR RR KR KK KR IR IR IR IR RII I I IORI AOI ACR IR ak ee ak / 


/* sbrk: Writes data */ 
/* Return value: First address of the area that was allocated*/ 
/[* (successful) * / 
/* -1: (failed) * / 


[BK RR KKK RR KK RR KK KR KK RR IR KR I RR RR I ROR TORR AOR AO RO a ee / 


char *sbrk(unsigned long size) /*Size of the area that is to be allocated*/ 


{ 


char *p ; 
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if (brk+size>heap_area.heap+HEAPSIZE) /* Checks the free area. */ 


return (char *)-1 ; 


p=brk ; /* Allocates an area. */ 
brk += size ; /* Updates the last address. */ 
return p ; 
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: SH-series simulator debugger interface routine | 


: -Input/output one character_ | 


. EXPORT _charput 
. EXPORT _charget 

SIM_I0O: .EQU H'0080 ;Specifies TRAP ADDRESS 
. SECTION P, CODE, ALIGN=4 


; _Ccharput: One character output | 


F C program interface: charput (char) | 


charput 
MOV .L O PAR, RO ; Sets output buffer address to RO 
MOV .B R4,@RO ; Sets output character to buffer 
MOV.L #O PAR, R1 ; Sets parameter block address to R1 
MOV.L #H'01220000, RO ; Specifies function code (PUTC) 
MOV .W #SIM IO, R2 ; Sets system call address to R2 
JSR @R2 
NOP 
RTS 
NOP 
- ALIGN 
O PAR: ;Parameter block 
.DATA.L OUT_BUF 
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; _charget: One character input | 


: C program interface: char charget (void) | 


ALIGN 4 
charget 
MOV.L #I_PAR,R1 ; Sets parameter block address to R1 
MOV.L #H'01210000,RO ; Specifies function code (GETC) 
MOV .W #SIM_ IO, R2 ; Sets system call address to R2 
JSR @R2 
NOP 
MOV.L I_PAR,RO ; Sets input buffer address to RO 
MOV.B @RO,RO ; Returns input data 
RTS 
NOP 
- ALIGN oe 
I_PAR: ; Parameter block 
DATA.L IN BUF 


OUT_BUF: 
-RES.L al ; Output buffer 
IN_BUF: 
.RES.L sh; ;Input buffer 
END 
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Appendix F ASCII Code List 


Table F.1 ASCII Code List 


Parity bit 


[= folelole|olelole| 

fmf fofel oe [+ [ets fete fel a 
fefofojo] © [we foatel[efelr|] |e 
fofofofe| + [sow[xon[ [+ falalel[a 
fofote[o| 2 [toa fme[ = [= fe|r [ep 
fofotele| =» [co feor[# [3s fe]ls|]eol[s 
fofefofo| + [eorfme|s [+ fo|[r[e[t 
fofefofel = [wru ferro [s [e [vu pe |. 
fofefefot «| wfemolsfefr[v[rl[. 
ofefefet 7 feat tien {7 fs fw Te Tw | 

E A ( h 

fefofofe[ = ~mfsato psf rt y[ify_ 
fefotefo[ a [a fer [= [= Ps [z[a pe 
efofefe| = fw pec ee 
4 < | || 


Cc \ 


+ 


ot 


< 


= 


mn 
oO 

8 
a 


< 


cc 
N 


A 


3/8 
ele 
EG 


C 


fefefefope tats - t= tele, 
elefefef fetes ts fof- fe 


S m 


Zz 


} 
— 
RUB 
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Appendix G_ Encoding Rules 


This compiler encodes symbol names to create unique symbol names in order to implement the 
functions of the C++ language specification and operator multi-definition functions. The encoding 
rules are described below. 


This compiler encodes the identifiers of the functions of the C++ programs without C linkage 
specified and static data members. 


function-encode-name= _ _(function-name-information)__F_ _(class-name- 
information)(qualifier-information)(parameter-information) 


static-member-encode-name=_ _(static-member-name)_ _(class-name-information) 


(1) Function name information 


As the function names, the user declared function names or one of the characters strings listed 
below in the case of a multi-definition operator function are inserted in the encode names. 


Table G.1 Operator Encodes 


Operator Encode Operator Encode 
operator ( ) __c¢l operator [ ] __vec 
(Calling function) (Adding subscript) 

operator new _ _nw operator delete __dl 
operator new [ ] _ _nwvc operator delete [ ] _ _dlivc 
operator T _ _op<T type function> operator* __ml 
(Conversion function) 

operator / _ _dv operator % ___md 
operator + __pl operator - _ _mi 
operator << __ls operator >> __rs 
operator = = _ _eqg operator ! = _ _ne 
operator < _lt operator > __gt 
operator < = __le operator > = __ge 
operator & __ad operator | _ _or 
operator * __er operator && __aa 
operator || _ _00 operator ! _ _nt 
operator ~ _ _co operator ++ _ _pp 
operator - - __mm operator = _ _as 
operator -> __rf operator + = _ _apl 
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Table G.1 Operator Encodes (cont) 


Operator Encode Operator Encode 
operator - = _ _ami operator * = _ amu 
operator % = _ _amd operator <<= _ _als 
operator >>= _ _ars operator &= _ _aad 
operator |= _ aor operator*= _ _aer 
operator , __cm operator ->* __rm 


(2) Class information 


For the class information, the number of characters for the class name and the class name 
character string are inserted in the encode. For a nested class, Q(nest-level)_(outermost-class- 
information)...(innermost-class-information) is inserted in the encode. 


(3) Qualifier information 


For the qualifier information, const, volatile, signed, or unsigned is inserted in one of encode 
character strings listed below. 


Qualifier Encode 
const Cc 
volatile Vv 
unsigned U 
signed Ss 


Note: S is not embedded regardless of whether or not signed is specified. For the signed char 
type, S is embedded. 
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(4) Parameter type information 


For the parameter type information, a basic type, a class type, or a drived type is inserted in the 


encode character string.. 


Type 


Encode 


void 


Vv 


char 


Cc 


short 


int 


long 


float 


double 


Qa;]~7 


long double 


Class name 


e 


(number-of-class-name-string-literal)(class-name- 


character-string) 


Pointer 
Reference 
Array 


Pointer to the member 


When the type is the same as for the 
n'th parameter 


p 
R 


A (number of elements)_ 


M (number-of-class-name-string-literal)(class-name- 
character-string) 


Tn (n indicates the n'th parameter) 
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Appendix H_ Execution Routine Naming Rules 


This appendix describes the naming rules of execution routine functions. 


Naming Rules of Integer Operation, Floating Point Operation, Sign 


_ [operation-name] [size] [sign] [r] [p] [nm] 


[Size] 1 byte 


Ww 
1 4 bytes 
4 bytes [single precision floating point] 
id point] 
[Sign] Signed 
uu 
[r] 
that of _subd or _divd. 
[p] Assigned at peripheral only 
[nm] No mask. Assigned only at Interrupt No Mask is set in peripheral. 


_muli 
Note: [Sign] is assigned for integer operation only. 


Conversion Function Naming Rules 


_ [size] to[size] 


1 Signed 4-byte 
Unsigned 4-byte 
:S 


:d_ Double precision floating point 
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H.3 Shift Function Naming Rules 


_[sta_]sft[direction][sign][number-of-bits] 


[sta_] :b 
[direction] :1 
a5 
[sign] ‘ll 
‘a 


Assigned only when the number of bits is assigned. 


Left shift 

Right shift 
Logical shift 
Arithmetic shift 


[number-of-bits] :b 0 to 31 


Notes: 1. [sign] is assigned only when [direction] is r. 


2. [number-of-bits] is assigned only when there is [sta_]. 


H.4 Naming Rules of Other Functions 


Area Move, String Literal Comparison, and String Literal Copy are the special cases. 
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Appendix I Interrupt Handlers 


This appendix shows examples of interrupt handlers of SH-3, SH-3E, and SH-4. 


p RRR RRR KERR RRR ERE REE KE EERE REE REE REE EKER ERR REE ERE KEKE EER REKKEKRKREKEEKER » 
; Interrupt Starter Routine 
RRR KERR KK RK KR KK KEKE ERK KK RRR RRR RRR RE KR RRR KEKE RRR KKK KERR KR EKKKEKEKEKER - 
. SECTION inthandl, CODE, ALIGN=4 
. ORG H’ 600 


-EXPORT int start 
-EXPORT__ int _term 


__ int start: 


stc.L SSR, @-R15 save ssr 
STC. SPC, @-R15 save spc 
MOV.L R8, @-R15 save work register 
ADD # -4, R15 sr stack area 
MOV .L RO, @-R15 save work register 
MOV.L R1, @-R15 save work register 
MOV.L INTEVT, RO set INTEVT address to r0 
MOV.L @RO, RO set exception code to r0 
CMP/EQ #0, if INTEVT <> 0 then 
BF label branch to label: 
MOV.L @R15+, R1 restore work register 
MOV.L @R15+, RO restore work register 
ADD #16, R15 
RTE 
NOP 

label: MOV.L R2, @-R15 save work register 
MOV .L INTEVT, RO set INTEVT address to r0 
MOV.L @RO, R1 set exception code to r1 
MOVA vettbl, RO set vector table address to r0 
SHLR2 R1 3bits shift-right exception code 
SHLR R1 
ADD # -(h’1c0>>3), R1 exception code —h’1c0 
MOV.L @(RO, R1), R8 set interrupt function addr to r8 
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MOVA imasktbl, RO 
SHLR2 R1 

MOV .B @(RO, R1), R1 
EXTU.B Ri Rd 

STC SR, RO 

LDC RO, SSR 
MOV .L IMASKclr, R2 
AND R2, RO 

OR R1, RO 

MOV.L RBBLclr, R1 
AND R1, RO 

MOV.L RO, @(12, R15) 
MOVA __int_term, RO 
LDC.L RO, SPC 

MOV .L @R15+, R2 

MOV .L @R15+, R1 
MOV.L @R15+, RO 
LDC.L @R15+, SR 

JMP @R8 

MOV .L @R15+, R8 


; set interrupt mask table addr to r8 
; 2 bits shift-right exception code 
; set interrupt mask to r1 


; save sr to r0 


set current status to ssr 


; set IMASK clear data to r1 
; Clear interrupt mask 

; set interrupt mask 

; set RB, BL clear data to r1 
; (RB =BL=0) 

; push sr 


; set__int_term addr to spc 


; restore work register 

; restore work register 

; restore work register 

; restore sr 

; Jump to interrupt function 


; restore work register 


ZR RRR RRR RRR KKK KR RK KKK KR KK ERK RRR KR KEKE RE KEK KERR REAR KER RKRKEKKEKRKEKEKRKEEER | 


; SH-3 Interrupt Terminator Routine 


p RRR RRR KKK RK KKK KKK KKK KK KKK KEK KK KKK KKK KKK KKK KKK KKK KKK KEKE KKK KKEKKKKKEKEER » 


-ALIGN 4 
__int_term: 
LDC.L @R15+, SPC 
LDC.L @R15+, SSR 
RTE 
NOP 
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; load spc 
; load ssr 
; rte 
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.ALIGN 4 
RBBLclr: .DATA.L H’4FFFFFFF 
IMASKclr: .DATA.L H’ FFFFFFOF 
INTEVT: .DATA.L H’FFFFFFD8 
vettbl: ; Interrupt Vector Table 
.DATA.L H’00000000 ; NMI 
.DATA.L H’00000000 ; IRL=0 
.DATA.L H’00000000 ; IRL=1 
-RES.L 26 
.DATA.L H’00000000 ; RCVI 
imasktbl: ; Interrupt Mask Table 
.DATA.B H’FO ; NMI 
.DATA.B H’FO ; IRL=0 
.DATA.B H’EO ; IRL=1 
.RES.B 26 
.DATA.B H’00 ; RCVI 
. END 


Note: The priority of the interrupts from the on-chip peripheral module set in imasktbl must be 
the same as the priority set in the interrupt level setting registers A and B (IPRA and 
IPRB). 
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Appendix J Reentrant Library 


The table below lists reentrant libraries. The functions that are marked with A in the table set the 
_errno variable. Therefore, the functions can be executed in reentrant unless the program reefers 
to _errno. 


Table J.1. Reentrant Library List 


No. Standard Include File Function Name Reentrant 
stddef.h 1 offsetof O 
2 assert.h 2 assert X 
3 ctype.h 3 isalnum O 
4 isalpha O 
5 iscntrl O 
6 isdigit O 
7 isgraph O 
8 islower O 
9 isprint O 
10 ispunct O 
11 isspace O 
12 isupper O 
13 isxdigit O 
14 tolower O 
15 toupper O 
4 math.h 16 acos A 
17 asin A 
18 atan A 
19 atan2 A 
20 cos A 
21 sin A 
22 tan A 
23 cosh A 
24 sinh A 
25 tanh A 
26 exp A 
27 frexp A 
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Table J.1. Reentrant Library List (cont) 


No. Standard Include File 
4 math.h 
(cont) 
5 setjmp.h 
6 stdarg.h 
7 stdio.h 
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28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 
50 
51 
52 
53 
54 
55 
56 
57 
58 
59 


Function Name 
Idexp 
log 
log10 
modf 
pow 
sqrt 
ceil 
fabs 
floor 
fmod 
setjmp 
longjmp 
va_start 
va_arg 
va_end 
fclose 
fflush 
fopen 
freopen 
setbuf 
setvbuf 
fprintf 
fscanf 
printf 
scanf 
sprintf 
sscanf 
vfprintf 
vprintf 
vsprintf 
fgetc 
fgets 
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Reentrant 


x) XK) Ob] x) &K) &] Oo] KY) KY] &K) KI | Xd) KI KI KIKI} O]O}] OO] O] OJ PJ E/E] Ee] Ee] e] eb] Ee] oe] be 


Table J... Reentrant Library List (cont) 


No. Standard Include File Function Name Reentrant 

7 stdio.h 60 fputc X 
61 fputs Xx 
62 getc Xx 
63 getchar Xx 
64 gets X 
65 putc Xx 
66 putchar xX 
67 puts xX 
68 ungetc X 
69 fread Xx 
70 fwrite X 
71 fseek xX 
72 ftell X 
73 rewind X 
74 clearerr X 
15 feof xX 
76 ferror X 
77 perror xX 

8 stdlib.h 78 atof A 
79 atoi A 
80 atol A 
81 strtod A 
82 strtol A 
83 rand xX 
84 srand X 
85 calloc xX 
86 free X 
87 malloc x 
88 realloc xX 
89 bsearch O 
90 qsort O 
91 abs O 
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Table J.1. Reentrant Library List (cont) 


106 strpbrk 
107 strrchr 


No. Standard Include File Function Name Reentrant 
8 stdlib.h 92 div A 
93 labs O 
94 Idiv A 
9 string.h 95 memcpy O 
96 strcpy O 
97 strncpy O 
98 strcat O 
99 strncat O 
100 memcmp O 
101 strcmp O 
102 strncmp O 
103 memchr O 
104 strchr O 
105 strcspn O 
O 
O 
108 strspn O 
109 strstr O 
110 strtok X 
111 memset O 
gf bP strerror O 
113 strlen O 
114 memmove O 


Reentrant column 
O: Reentrant 
x: Non-reentrant 


A: _errno is set. 
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